Forem: Sebastian Weber

Java - Don't use raw types

Sebastian Weber — Fri, 17 Dec 2021 12:45:56 +0000

I'm re-learning Java, which I have already dealt with in large parts of the 2000s. In addition to pair-programming with my experienced work colleagues, I plan to pick out language features and concepts, and deal with them more intensively. In this article I describe my learnings about the chapter "Don't use raw types" part of the excellent book "Effective Java". This constitutes a good starting point to learn about generics.

The key message from the article is to never ever opt-out from the generic type system. Using raw types prevents the compiler to raise errors at development time. Instead, you might come up with runtime errors. Tracking down the bug might be difficult because the issue might occur in a completely other spot away from the source of evil.

The chapter is all about generics. It is a good source to learn about different concepts and terminology of generics. It focuses on the advantages of using the generic type system and contrasts the problems of raw types.

It is also important to note that the examples below to discuss the topic of the book chapter are by no means good practice. There exists advanced generics features like bounded types and bounded wildcard types that should be used in professional projects. You should also never work with the type Object!

List<E> is an example of a generic interface, because it's declaration consists of at least one type parameter, in this case E. There exists generic classes, too. Both, generic interfaces and classes, can also be called generic types.

List<String> is a parameterized type, which elements are of type String. Thereby, List is the actual raw type, String represents the type parameter, and E constitutes the formal type parameter defined in the type declaration (List<E>).

This article explains why you shouldn't use raw types directly. The question is why does Java allow it in the first place? For compatibility reasons there still exist this concept, because generics have been first introduced with JDK 5.0. That's the reason why the compiler even with recent JDK versions erases all generic type information. So, in the end you come up with code that uses raw types directly.

In fact, before the introduction of generics, there only existed raw types, so you had to use List directly and cast its elements manually. It's still legal to use generic types without their type parameters in the old way.

List myHobbies = new ArrayList();
myHobbies.add(new Coding());
myHobbies.add(new Crossfit());
Crossfit crossfit = (Crossfit) myHobbies.get(1);

This works but is not recommended. The compiler points this out with unchecked call warnings.

Why is this code problematic? Because you have to know the concrete types of every item to make the correct cast. This is a real problem with dynamic code.

for (Iterator hobbiesIterator = myHobbies.iterator(); hobbiesIterator.hasNext();) {
    Crossfit hobby = (Crossfit) hobbiesIterator.next();
    System.out.println(hobby);
}

This compiles but it leads to a runtime error due to a illegal cast.

The correct way is to utilize generic type parameters in case you use generic classes or generic interfaces. Using the wrong types leads then to compiler-time errors.

List<Crossfit> moreHobbies = new ArrayList<>();
moreHobbies.add(new Crossfit());
moreHobbies.add(new Coding());

But I would like to use different hobbies (i.e., different types) in my list, what can I do - yes, it's clear to me that this is a bad idea. Ok, then you better use List<Object>.

List<Object> evenMoreHobbies = new ArrayList<>();
evenMoreHobbies.add(new Crossfit());
evenMoreHobbies.add(new Coding());

This is a parameterized type representing a list that can contain objects of any type. What's the difference to using the raw type List? Again, you lose all the safety and expressiveness benefits that the generic type system provides. The difference is subtle. List<Object> gives the compiler more information of what you have in mind as a developer: You explicitly tell the list is capable of holding any type of objects.

One consequence is that the compiler does not allow to assign a list of strings to a list of objects due to sub-typing rules: List<String> is a sub-type of raw type List but not of the parameterized type List<Object>. Thereby, the compiler guarantees that you can only add values of type Object.

List list1;
List<String> stringList = new ArrayList<>();
list1 = stringList;

List<Object> list2;
list2 = stringList;

Let's explore more what you give up when you opt-out of the generic type system, i.e., what it means to loose type-safety.

List<String> strings = new ArrayList<>();
strings.add(Integer.valueOf(23));

Adding a number to our string list is prevented by the compiler. This is an example for utilizing type-safety of generics.

However, the following unsafeAdd method bypasses the type-safety mechanism.

public static void main(String[] args) {
  List<String> strings = new ArrayList<>();
  unsafeAdd(strings, Integer.valueOf(41));
  String s = strings.get(0); // compiler-generated cast
  s.contains("hello world"); // runtime-error
}

private static void unsafeAdd(List list, Object o) {
  list.add(o);
}

Because we extracted the code for adding into a method that adds a Object to a raw type list, we cause a runtime error.

Again, we ignore the compiler warnings and take negligently the risk of a runtime error.

If you are in the situation that you have a method to work on a list (or other raw type) whose element types are unknown or you don't care about them, you better use unbounded wildcard types (List<?>). So the major reason to use the wildcard version is to maintain type-safety.

You might ask, what's the difference between List<Object> and List<?>?

List<Object> objList = new ArrayList<>();
List<?> wildcardList = new ArrayList<String>();
objList.add(""); // works
wildcardList.add("");// compile-time error

You cannot assign a value to a list of wildcard type. But you can leverage it for type-save checks. Consider the following code, where a Stats class with a bounded type (T extends Number) is defined to calculate the average of numeric values.

class Stats<T extends Number> {
    T[] numbers;

    Stats(T[] o) {
        numbers = o;
    }

    double average() {
        double sum = 0.0;
        for (int i=0; i < numbers.length; i++) {
            sum += numbers[i].doubleValue();
        }
        return sum / numbers.length;
    }

    boolean sameAverage(Stats<?> o) {
        if (average() == o.average()) return true;
        return false;
    }
}

public static void main(String[] args) {
  Integer intNumbers[] = { 2, 4};
  Stats<Integer> intStats = new Stats<>(intNumbers);
  Double doubleNumbers[] = { 2.0, 4.0 };
  Stats<Double> doubleStats = new Stats<>(doubleNumbers);

  System.out.println("same average? " + intStats.sameAverage(doubleStats));
  // System.out.println("same average? " + intStats.sameAverage(23)); // compile-time error
  // System.out.println("same average? " 
  // + intStats.sameAverage(new Stats<String>("hello world"))); // compile-time error
}

The method sameAverage makes use of a wildcard type. You cannot pass anything into the method other than a numeric value (i.e., a sub-class of Number). You have to understand that the wildcard does not affect what type of Stats objects can be created or what actual type can be passed to the sameAverage method. The class declaration (T extends Number) does this.

A key take-away of this article is to never use raw types and instead use the generic type system. Then, the compiler has the possibilities to find wrong type assignments already at development time.

Efficient Code Analyzing and Formatting (for React) with ESLint, Prettier and VSCode: 2020 Edition

Sebastian Weber — Mon, 24 Feb 2020 22:20:38 +0000

Two years ago, I wrote an article on how to setup a development workflow utilizing ESLint for static code analysis and Prettier for beautifying code. It was in the context of Vue.js but 99% of the concepts and related technologies are independent of the actual frontend development framework. Meanwhile, I use React on a daily basis on my job project.

As you most likely know, things are steadily changing in "frontend world". That's why I come up with a 2020 remake of my original article (which targeted Vue.js – but it doesn't matter). However, I do not want to rehash the old article by duplicating chapters. Instead, I focus only on the technical details:

related npm dependencies
general ESLint / Prettier config
React related config
VSCode integration

If you are interested in the underlying concepts, please feel free to check out my former article:

What is ESLint, what is Prettier, how they differ
How to integrate ESLint with Prettier
What are possible workflows (terminal, git hooks, IDE, etc.)
IntelliJ integration

React Project Setup

The easiest thing to launch a running React project is to use create-react-app.

$ npx create-react-app react-project

Go to the package.json file, remove the eslint-config object.

"eslintConfig": {
  "extends": "react-app"
}

Add the following devDependencies.

"devDependencies": {
  "babel-eslint": "^10.0.3",
  "eslint": "^6.8.0",
  "eslint-config-babel": "^9.0.0",
  "eslint-config-prettier": "^6.10.0",
  "eslint-plugin-import": "^2.20.0",
  "eslint-plugin-prettier": "^3.1.2",
  "eslint-plugin-react": "^7.18.0",
  "eslint-plugin-standard": "^4.0.1",
  "prettier": "^1.19.1"
}

You can learn more about this dependencies by reading my old article.

TLTR;
With this setup you can integrate ESLint with Prettier in a way that code formatting is turned off for ESLint (eslint-config-prettier) and runs Prettier as an ESLint rule (eslint-plugin-prettier. eslint-plugin-standard and eslint-plugin-react are two of the supported plugins.

Of course you have to install the dependencies:

$ npm i

The final step is to add a .eslintrc.json file to the root folder with the following content:

{
  "extends": [
    "prettier",
    "prettier/standard",
    "prettier/react",
    "plugin:react/recommended"
  ],
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  },
  "parser": "babel-eslint",
  "env": {
    "browser": true
  },
  "settings": {
    "react": {
      "pragma": "React",
      "version": "detect"
    }
  }
}

Required Visual Studio Extensions

You need to install two VSCode extensions to get a pretty awesome developer UX. First, you have to install the Prettier plugin. In addition, you need the ESLint plugin as well. Just search in the extension section for the keywords "eslint" and "prettier" and make sure to install the correct ones, from Dirk Baeumer and Esben Petersen, respectively.

A nice feature of VSCode is to add recommended extensions to your project. It can be useful to get new developers productive fast. All you need to to is to add .vscode folder to the root of your project and add a extensions.json file with the following content:

{
  "recommendations": [
    "dbaeumer.vscode-eslint", 
    "esbenp.prettier-vscode"
  ]
}

For your colleagues it then looks like this.

Setup Format on Save

The final part of setting up VSCode is to provide the auto save configuration in the workspace settings. Fire up the command palette with ⇧⌘P and type "open workspace settings". Switch to the json editor. Put the following code inside the json file:

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.formatOnSave": false
  },
  "[javascriptreact]": {
    "editor.formatOnSave": false
  }
}

The last two properties are necessary for me to turn of other formatting mechanism that have nothing to do with ESLint or Prettier.

By now I think it is a good idea to have these settings under version control. This workspace settings are located in .vscode/settings.json of your project. It can help to eliminate different VSCode setups among your colleagues. At least it saves time for recurring work.

At the latest after a restart of VSCode format on save should work as expected for JSX and javascript code as well as json and css files.

Demo Project

You can check out my demo project to see all this in action. Just perform the following steps:

clone the project
install the dependencies

$ npm install

Optional: Install the VSCode extensions for ESLint and Prettier. Go to the Extension section, enter @recommended into the Search Extensions in Marketplace search field, and install both extensions.

Go to javascript, json or css files, change them and press save. The file should be reformatted.

Conclusion

The setup became even easier than 2 years ago. However, many vectors change, so that it is always a bit complicated to find the interaction between all technologies. In addition, you can find outdated information on the net, which does not make life any easier. To fix the problem for February 2020, this article was created 😀.

Cover image by Alex Kotliarskyi.

Upgrade macOS to Utilize Keyboard Shortcuts for a more Productive Development Workflow

Sebastian Weber — Tue, 19 Nov 2019 21:37:48 +0000

Using a mouse or trackpad is a major distraction and flow-breaker for many development tasks, especially programming. I strive for using keyboard shortcuts as much as possible to be more productive while programming.

Out of the box, macOS does not provide many keyboard shortcuts when it comes to window management. As an example, there is no way to move a focused window to another space by keyboard.

In this article I want to present my curated list of useful tools to manage windows, displays, and spaces (of Mission Control) without a mouse. I hope you retire your mouse after reading this post. 😉

Alfred – Application Launcher on Steroids

Alfred is an elite application launcher and utility to search and find files on your machine or on the Web. I use Alfred instead of Spotlight. The hotkey to open up the launcher panel has been burned into my brain for a long time. Of course, you can define a custom key combo in Alfred's settings.

Alfred is very versatile, you just have to fire up the panel with your defined hotkey and you can start typing. Most of the time I type the starting characters of an app I want to launch. However, you can do more from this input field, e.g., start a google search as you can see from the next screenshot (marked by ⌘5).

To open a file or folder on your machine, start typing open and Alfred assists you with recommended actions shown in the result list.

Alfred has many more awesome features like snippets or workflows, which I will not cover here. Take a look at Alfred's power pack. I want to point out one awesome feature and that is Clipboard History. You can define a shortcut in the Features section of Alfred's settings.

If you press the defined hotkey, a clipboard history panel appears and allows you to paste more than the last copied item.

Spectacle – The Missing Window Resizer

Spectacle is an awesome tiny tool that allows for changing the size or position of a particular window. It upgrades macOS in a way that you can use keyboard shortcuts to resize or move focused windows of any app. Sophisticated window management by shortcuts is one aspect I have missed from Microsoft Windows when I was working on a project with PCs as development machines.

In my current project, I have an environment with two external displays in addition to the built-in display of my MacBook. Spectacle provides
customizable shortcuts even for throwing a focused window to another display. Therefore, you can specify shortcuts in Spectacle's settings dialog for Next Display and Previous Display.

Besides moving windows from one visible display to another, I highly use shortcuts to resize windows like Make Larger, Make Smaller, or Left Half.

I appreciate Spectacle's simplicity. You have a nice glasses icon in the menu bar to see all window actions along with keyboard shortcuts at a glance.

The following recording gives an impression how Spectacle works. I used the shortcuts as you can see in the screenshot above.

Spectacle is brilliant, however, it lacks one feature I really need. I need to move windows also to invisible spaces. Spectacle only allows to move windows between visible spaces (i.e., displays) by defining shortcuts for Next Display and Previous Display. Luckily, the next tool can help out.

Amethyst – A Handy Tiling Window Manager

Amethyst constitutes a tiling window manager for macOS. It has some features in common with Spectacle, e.g., increasing and decreasing window sizes by shortcuts. However, as you can see from the screenshot about Amethyst's settings, the tool provides many more useful shortcuts.

My personal killer feature is the ability to throw focused windows to a particular space. I very often move a window to the left or right space (Throw focused window to space left or Throw focused window to space right).

Another very handy feature does not require using shortcuts at all. Amethyst rearranges windows on a display automatically (i.e., visible space in focus). As an example, if you have a single browser window on your active display and you open another browser window by ⌘ N, both windows are positioned next to each other with the exact same width and height. If you put another window of any software on this display, all three windows are rearranged again in a way that there is no overlapping. Wicked!

Contexts – An Improved Command-Tab Switcher

I use Contexts primarily for an improved "Command-Tab switcher".

Contexts adds the ability to select individual windows by using the learned key combos ⌘ ⇥ and ⇧ ⌘ ⇥ (to move up the list). In the settings you can also define other shortcuts for these actions. Additionally, you can also use multiple shortcuts for invoking the window switcher with individual settings, which is not possible with macOS default switcher.

As you can see from the previous screenshot, you can define any number of shortcuts to activate the window switcher and to move the list up and down. What I really like is that you can restrict the list for every shortcut, e.g., show only visible spaces.

Another major time saver is Contexts' search capability. Actually, it acts more like a filter for the window list. When you have activated the switcher panel, you can just start typing (with pressed hotkey) and, thereby, filter the list to save the time for moving up and down the list.

You can even optimize this workflow by defining a modifier key to activate and use the fast search feature. To switch to a window, press this modifier key and type a few characters from the app name or window title. As you can see from a previous screenshot, on the left-hand side of the switcher panel characters are shown that show you suitable strings for fast search.

What I also like is that I can remove particular apps from the switcher panel's list, e.g., macOS Finder, because I'm not convinced of this tool and use instead an alternative.

macOS Build-in Shortcuts

There are some shortcuts to use Mission Control without a mouse. For me, the most important one is to switch between spaces by pressing ⌃ ← or ⌃ →. To open Mission Control or show its spaces bar press ⌃ ↑. To show all windows of an application side by side press ⌃ ↓.

Of course, the following shortcuts should become second nature if you want to be productive on a Mac. ⌘ Q quits applications along with all its windows. To close a focused window press ⌘ W. To copy and paste things use ⌘ C and ⌘ V.

Another useful shortcut during my office hours is locking the screen by pressing ⌃ ⌘ Q. In addition, a useful shortcut to kill none-responding applications is ⌥ ⌘ ESC.

KeyCue – Shortcus Always at a Glance

If you cannot remember these system shortcuts, you can take a look at the application menu. If a command provides a shortcut, you can find it on the right side of the menu entry. An even faster approach is to use KeyCue. It's a useful tool to show all shortcuts of the current application which is currently in focus along with system shortcuts. The goal of KeyCue is to find, remember, and learn keyboard shortcuts.

You can show the list of shortcuts for a focused app from the keyboard. As an example, I configured KeyCue to show the list by pressing the ⌘ key for 1.5 seconds.

Summary

I want to point out that the presented tools provide way more features. However, these are the most important capabilities for me to reduce mouse usage.

Resizing and moving windows between visible and none-visible spaces with just a few keystrokes has significantly improved my productivity during a course of a day. I hope I could provide you some inspiration to improve your development workflow.

Yarn Workspaces does not Honor .npmrc Location Precedence: Implications and Possible Solutions

Sebastian Weber — Fri, 04 Oct 2019 14:33:48 +0000

Yarn Workspaces has a bug that does not respect the location precedence of .npmrc / .yarnrc files to configure registry settings if you run a yarn command in a selected workspace. Consider the following situation:

A .npmrc file located at home folder specifies a registry entry to use a private npm registry.
A .npmrc file located at a project root specifies a registry entry to target a public npm registry like this registry=https://registry.npmjs.org.

In my current project, I have such a situation. The default situation is that projects need a registry setup to use the internal Artifactory. One project requires a setup to target the public npm registry. The problem of this project is that adding a dependency to a specific yarn workspaces package with the following command uses the wrong registry setup (the setup of ~/.npmrc instead of .npmrc file located at project root):

$ yarn workspace package-a add @rooks/use-previous

The problem is that wrong URLs are put into the yarn.lock file (targeting the private registry).

However, if you add a dependency globally with the -W flag, then the .npmrc precedence is honored:

$ yarn add @rooks/use-previous -W

This bug seems to exist for a very long time.

The following workarounds are possible:

Use the --registry flag

$ yarn workspace package-a add @rooks/use-previous --registry 'https://registry.yarnpkg.com'

Manually add the dependency to the package.json of package-a and run yarn install from the root folder of the project.
Copy ~/.npmrc to every project root folder that need this registry setup and delete ~/.npmrc. If you have private settings (e.g., your user credentials) in the file, pay attention that you do not push the file to VCS (add it to .gitignore).
Don't use yarn workspaces. E.g., use Lerna with npm.

Testing of a Custom React Hook for Fetching Data with Axios

Sebastian Weber — Sun, 14 Jul 2019 09:59:49 +0000

Hooks is a new concept of React. It requires some rethinking of existing knowledge. Furthermore, developing React components with hooks requires a mind shift (e.g., don't think in lifecycle methods). It needs some time to get comfortable, but with some practice hooks can be incorporated into real-life projects without problems. Custom hooks are very useful to encapsulate logic into isolated modules that can be easily reused.

However, testing hooks is (currently) no easy task. It took me quite some time to write working tests for my custom hooks. This post describes the crucial aspects for testing them.

You can find the code for the custom hook as well as the corresponding tests in my Code Sandbox.

The Custom Hook

This article expects you to know how to write custom React hooks. If you are new to this topic, check out React's documentation. Another good starting point is to take a look at awesome-react-hooks.

The following code snippet constitutes a simple custom hook to perform a GET request with axios.

// useFetch.js
import { useState, useEffect } from "react";
import axios from "axios";

// custom hook for performing GET request
const useFetch = (url, initialValue) => {
  const [data, setData] = useState(initialValue);
  const [loading, setLoading] = useState(true);
  useEffect(() => {
    const fetchData = async function() {
      try {
        setLoading(true);
        const response = await axios.get(url);
        if (response.status === 200) {
          setData(response.data);
        }
      } catch (error) {
        throw error;
      } finally {
        setLoading(false);
      }
    };
    fetchData();
  }, [url]);
  return { loading, data };
};

export default useFetch;

The following code shows how this custom hook can be used.

import React from "react";
import ReactDOM from "react-dom";
import "./styles.css";

import useFetch from "./useFetch";

function App() {
  const { loading, data } = useFetch(
    "https://jsonplaceholder.typicode.com/posts/"
  );

  return (
    <div className="App">
      {loading && <div className="loader" />}
      {data &&
        data.length > 0 &&
        data.map(blog => <p key={blog.id}>{blog.title}</p>)}
    </div>
  );
}

const rootElement = document.getElementById("root");
ReactDOM.render(<App />, rootElement);

Testing the Custom Hook

At the time of this writing, testing hooks is no straight forward task. React's official documentation provides only a tiny section on this topic. I had a hard time to test hooks because of violations against the rules of hooks.

However, I've discovered react-hooks-testing-library that handles running hooks within the body of a function component, as well as providing various useful utility functions.

Before you write your tests, you need to install the library along with its peer dependencies as described in the documentation:

$ npm i -D @testing-library/react-hooks
$ npm i react@^16.8.0
$ npm i -D react-test-renderer@^16.8.0

The custom hook utilizes axios for fetching data. We need a way to mock the actual networking. There are many ways to do this. I like axios-mock-adapter making it easy to write tests for successful and failing requests. You need to install these libraries, too.

$ npm i axios
$ npm i -D axios-mock-adapter

First, take a look at the following Jest test, before we discuss the crucial parts.

// useFetch.test.js
import { renderHook } from "@testing-library/react-hooks";
import axios from "axios";
import MockAdapter from "axios-mock-adapter";

import useFetch from "./useFetch";

test("useFetch performs GET request", async () => {
  const initialValue = [];
  const mock = new MockAdapter(axios);

  const mockData = "response";
  const url = "http://mock";
  mock.onGet(url).reply(200, mockData);

  const { result, waitForNextUpdate } = renderHook(() =>
    useFetch(url, initialValue)
  );

  expect(result.current.data).toEqual([]);
  expect(result.current.loading).toBeTruthy();

  await waitForNextUpdate();

  expect(result.current.data).toEqual("response");
  expect(result.current.loading).toBeFalsy();
});

The implementation of useFetch performs a network request with axios. Therefore, we mock the GET request before we call useFetch.

// ...
const mock = new MockAdapter(axios);
// ...
/* 
  Mock network call. Instruct axios-mock-adapter 
  to return with expected data and status code of 200.
*/
mock.onGet(url).reply(200, mockData);
// invoke our custom hook
const { result, waitForNextUpdate } = renderHook(() =>
  useFetch(url, initialValue)
);

As you can see, useFetch is wrapped in a renderHook function invocation. What this actually does is to provide the correct context to execute the custom hook without violating the rules of hooks (in this case that hooks can only be called inside the body of a function component).

The renderHook call returns a RenderHookResult. In our example, we destructure result and waitForNextUpdate from the result object. Let's discuss result first.

// ...
const { result, waitForNextUpdate } = renderHook(() =>
  useFetch(url, initialValue)
);

expect(result.current.data).toEqual([]);
expect(result.current.loading).toBeTruthy();
// ...

result constitutes the renderHook result. As you can see in the expect statement, we can access the actual return value of our custom hook from result.current. So result.current.data and result.current.loading hold the return value of the custom hook call. These two assertions evaluate to true. The data state holds the passed initial value and the loading state is true because the actual network call has not been performed yet.

So far, so good, but how do we perform the call? Therefore, we need waitForNextUpdate.

// ...
const { result, waitForNextUpdate } = renderHook(() =>
  useFetch(url, initialValue)
);

expect(result.current.data).toEqual([]);
expect(result.current.loading).toBeTruthy();

await waitForNextUpdate();

expect(result.current.data).toEqual("response");
expect(result.current.loading).toBeFalsy();

waitForNextUpdate allows us to wait for the asynchronous function to return in order to check the response of the network call.

The following extract is from the lib's documentation:

[...] returns a Promise that resolves the next time the hook renders, commonly when state is updated as the result of an asynchronous action [...].

After await waitForNextUpdate() returns we can safely assert that result.current.data holds data coming from the (mocked) network request. In addition, a state change by calling setLoading(false) was performed and, thus, result.current.loading is false.

Testing More Use Cases

In the following, you see a code snippet with two additional tests. The first one tests if our hook implementation can handle multiple invocations. The second one checks the network error case with the help of axios-mock-adapter.

test("useFetch performs multiple GET requests for different URLs", async () => {
  // fetch 1
  const initialValue = "initial value";
  const mock = new MockAdapter(axios);

  const mockData = 1;
  const url = "http://mock";
  mock.onGet(url).reply(200, mockData);

  const { result, waitForNextUpdate } = renderHook(() =>
    useFetch(url, initialValue)
  );

  expect(result.current.data).toEqual("initial value");
  expect(result.current.loading).toBeTruthy();

  await waitForNextUpdate();

  expect(result.current.data).toEqual(1);
  expect(result.current.loading).toBeFalsy();

  // fetch 2
  const url2 = "http://mock2";
  const mockData2 = 2;
  mock.onGet(url2).reply(200, mockData2);

  const initialValue2 = "initial value 2";
  const { result: result2, waitForNextUpdate: waitForNextUpdate2 } = renderHook(
    () => useFetch(url2, initialValue2)
  );

  expect(result2.current.data).toEqual("initial value 2");
  expect(result2.current.loading).toBeTruthy();

  await waitForNextUpdate2();

  expect(result2.current.data).toEqual(2);
  expect(result2.current.loading).toBeFalsy();
});

test("useFetch sets loading to false and 
returns inital value on network error", async () => {
  const mock = new MockAdapter(axios);

  const initialValue = [];
  const url = "http://mock";

  mock.onGet(url).networkError();

  const { result, waitForNextUpdate } = renderHook(() =>
    useFetch(url, initialValue)
  );

  expect(result.current.data).toEqual([]);
  expect(result.current.loading).toBeTruthy();

  await waitForNextUpdate();

  expect(result.current.loading).toBeFalsy();
  expect(result.current.data).toEqual([]);
});

Conclusion

I really like the API of react-hooks-testing-library. But what I like most is that the library enables me to test custom hooks in the first place. IMHO testing with this lib is straightforward.

If you see annoying warnings in the console as shown in the following screenshot, chances are high that you can fix it by updating your dependencies.

The act warning has been resolved with the react@^16.9.0 and @testing-library/react-hooks@^2.0.0 releases.

How are CSS Styles Applied to HTML Elements? Understand the Cascade!

Sebastian Weber — Tue, 28 May 2019 21:57:58 +0000

Normally, beginning your journey with CSS entails a steep learning curve. However, mastering CSS is hard since it is such a broad topic in itself. The field of applications is diverse, thus understanding the basics helps you to become a more productive developer.

Sure, having a more or less understanding is most of the time sufficient. Applying the trial and error method until your selectors do what you want does most of the time the job. However, in big projects you will sooner or later struggle with side effects or other weird bugs without understanding precedence in CSS.

Precedence

As a reminder, take a look at the structure of a CSS rule.

If several CSS rules target the same HTML element and these rules constitute definitions with one or more mutual CSS properties, which styles are applied by the browser in the end? This is where CSS precedence comes into play.

Examples help to make complex situations more understandable. Take a look at the following code snippets (or play around with the Codepen).

<!-- HTML template code -->

<h2 class="subline">subline</h2>
<aside>
  <h2>sidebar title</h2>
</aside>

/* some styles to target h2 elements */

.subline {
  font-family: serif;
}
h2 {
  font-family: sans-serif;
}
aside {
  color: red;
}

In the end, the sidebar title element has a sans-serif and red font applied. The subline element has a black serif font.

Several interesting things happened here. There is no selector that explicitly target a h2 element to assign a font color. However, the red color of the sidebar title was inherited by its parent element (aside). The second CSS font-family declaration (h2 selector) was not applied by the subline element because the .subline selector was considered as more specific by the browser.

All these aspects are considered to determine which CSS declarations for every DOM element have to be applied. If multiple CSS declarations (e.g., font-family: serif; and font-family: sans-serif;) with the same CSS property (color) are found to target a particular DOM element (e.g., the sidebar title), the browser creates a precedence order. Thereby, the property value with the highest precedence gets applied.

As you can see from this simple example, many aspects play a role in the browser process of determining the actual CSS styles. To be more specific, the following concepts are part of the precedence algorithm:

specificity
inheritance
the cascade

Specificity

Take a look at the following CSS snippet. It shows a bunch of selectors to style li elements.


.challenge li::before {
  content: '😃';
  margin-right: .25em;
  vertical-align: middle;
}

.challenge > ul li::before {
  content: '😴';
}

ul[data-smiley='crying'] > li::before {
  content: '😭';
}

The corresponding HTML elements are shown next.

<main class="challenge">
  <ul class="list">
    <li>1.1</li>
      <ul class="list">
        <li>2.1</li>
        <li>2.2</li>
        <ul class="list" data-smiley="crying">
          <li>3.1</li>
          <li>3.2</li>
          <li>3.3</li>
        </ul>
        <li>2.3</li>
      </ul>
    <li>1.2</li>
    <li>1.3</li>
  </ul>
</main>

If you specify multiple selectors to target the same HTML element, the browser picks the selector with the highest specificity value.

What is selector specificity all about? Specificity constitutes the amount of importance each CSS declaration block has in comparison with others based on what its selector is made up of. It is important to understand that specificity only relates to the selector. This means, the actual CSS declaration block is irrelevant in the context of specificity. However, specificity values are calculated by the cascade algorithm to bring these CSS declaration blocks in some kind of importance order. Based on this, styles are determined to apply to HTML elements.

The Specificity Calculator is a nice online tool constituting a visual way to understand this concept.

The first selector has a higher specificity because classes are more specific than elements.

You can think of selector specificity as a row vector of 4 elements as depicted by the illustration of CSS Tricks.

Consider the following examples:

selector 1 (0,1,0,0) wins over selector 2 (0,0,0,41)
selector 1 (0,2,0,1) wins over selector 2 (0,1,2,15)

Take a look at the following example that consist of two special cases.

  * {
    color: red;
  }

  h1#title {
    color: blue;
  }

  h1 {
    color: green !important;
  }

The universal selector (*) has a specificity of (0,0,0,0). The !important keyword beats everything, thus use it with care (or better don't use it). In the example, every h1 element has a green color, even the element with the id title. To override such a declaration, your only chance is to specify another declaration with !important, so order is relevant.

Over 10 years ago, Andy Clarke published an awesome article explaining selector specificity through Star Wars.

It is a fun way to learn the concept of specificity. I also recommend Emma Wedekind's in-depth explanation of CSS specificity.

Inheritance

Inheritance controls what happens if no value for a CSS property has been defined for an element. To be more precise, the inheritance mechanism propagates CSS property values from a parent element to its child elements. However, not every property value gets inherited. MDN's CSS property reference can be used to find out if the values of a particular property gets inherited or not. As you can see from in the following screenshot, margin does not get inherited by default.

A comprehensive list of all CSS properties with information about inheritance provides W3C.

Consider the following example.

<article>
  <h2>Title</h2>
  <p>Lorem Ipsum</p>
</article>

article {
  margin: 10px;
}

p {
  margin: inherit;
}

By using the inherit keyword, the margin property value of the article element gets propagated to the p element. In contrast, the h2 element does not inherit the margin value of its parent since margin does not get inherited by default.

The following Codepen constitutes a more comprehensive example of CSS inheritance.

The Cascade

CSS stands for Cascading Style Sheets, so it is not surprising that the cascade plays an important role. This algorithm calculates the above explained precedence for all CSS declarations. Thereby, it also considers specificity and inheritance to determine which styles are applied to every HTML element of your HTML document.

The simplified algorithm looks like this (for complete details refer W3C specification). The algorithm is executed for every HTML element:

Collect every CSS declaration that comes into question for the current HTML element.
Sort these declarations by origin and weight.
- Origin refers to the location where the declaration is specified (e.g., inline styles as style attribute or within an externally defined stylesheet file).
- Weight equals importance of the declaration, i.e., author styles (styles that we developer provide) > user styles (styles specified by end-users, e.g., in Firefox) > browser defaults (e.g., most desktop browsers define 16px as default font-size for html elements).
- The following rules are valid for author styles: inline styles > styles defined within the head element > styles part of external files
- !importance (e.g., p { color: red !important; }) constitutes a higher weight than normal CSS declarations.
Sort all selectors targeting the current HTML element by specificity values (the highest value on top of the list).
Are two CSS declarations equal regarding all rules above, the declaration wins that is specified later in terms of document flow. So order acts as tie-breaker in such situations. Order comprises the location where styles are integrated: integrated external stylesheets within the head element but also imported stylesheets (with @import declaration) from within external stylesheet files.

The following illustration explains the algorithm in a nutshell.

Let's briefly discuss how the cascade effects on inheritance. What happens if you have two ancestors of an element with the same properties that gets propagated down the document tree due to inheritance? Ultimately, the property values of the ancestor that is closest to the element are applied.

If you would like to have another perspective on the cascade, I recommend Benjamin Johnson's article.

Utilize browser dev tools

Developer tools of modern browsers are very helpful to grasp the concept explained in this article. The next annotated screenshot shows how information regarding inheritance and precedence (crossed out declarations, origin of styles, etc.) are visualized by Chrome dev tools.

This picture constitutes a screenshot of a Codepen with annotations to show why which CSS declaration is applied or not applied by the algorithm. Concrete, the annotations represent the analysis for the <h2 class=”subline”>Subline</h2> element (marked by blue arrow).

Conclusion and Lessons Learned

The cascade is the system managing styles from multiple sources and determines what declarations take precedence in case of conflicts. The cascade algorithm considers styles that are directly applied to HTML elements as well as styles for HTML elements that are not explicitly defined (i.e., inherited styles).

Especially for beginners, it might not be clear that the cascade "collect" styles from different sources: explicit defined, inherited, default styles, etc.

IMHO a solid understanding of the cascade algorithm is the key for becoming a better Web developer. If you understand how the browser applies styles to HTML elements, you can avoid frustration in development projects (e.g., unwanted applied styles or side effects).

It turns out that the cascade algorithm is actually easy to understand and memorize. Most of the time, you only deal with author styles so the number of rules to remember is not that large. If you are familiar with specificity and inheritance you are good to go. Further, if you have a good CSS design you do not have to think much about document flow because you most likely do not spread styles all over your stylesheet files.

Why does React Hooks enable writing simpler code? 🎣

Sebastian Weber — Thu, 23 May 2019 06:40:58 +0000

While learning React Hooks I have read a lot about the conceptual decisions of the React team. E.g., they state that React components with React Hooks are easier to write and understand as Class components.

Why do you think writing projects with React Hooks will lead to more understandable and maintainable code?

Master Flexbox Scaling by Understanding flex-grow, flex-shrink, and flex-basis

Sebastian Weber — Wed, 15 May 2019 18:45:58 +0000

Inspired by an article why flex-grow is weird, I've developed a small tool (Codesandbox) to explore how different properties of flex items work separately or in combination. You can reproduce all examples of this article with my tool. I hope you find it useful.

In case this tool is not intuitive for you, this article breaks down different combination of flex-basis, flex-grow, and flex-shrink to show how these flexibility properties can be leveraged for responsive flexbox layouts.

flex-basis

Take a look at the next screenshot.

First of all, the blue annotations explain how the tool works. In this example, the 2 flex items (blue = flex item 1 and green = flex item 2) do not consume the whole available space of the flex container (width of 500px). 100px free space is represented by 2 grey-scaled squares (500px / 10 segments). The grey-scaled ruler is meant as utility to visualize how many "portions" of the flex container are free for distribution.

The next example shows both width and flex-basis.

So what is the difference between width and flex-basis In case you specify both properties (green flex item), width is ignored. The blue flex item does not specify flex-basis so the item automatically gets the default property (flex-basis: auto). In such a case, width is used for scaling.

Dave Geddes compiled an in-depth explanation on the difference between width and flex-basis.

flex-shrink

As you can see in the next example, flex-basis can cause an overflow of the flex container.

However, specifying a flex-shrink value fixes the problem by allowing the blue flex item to shrink.

You can specify flex-shrink for every flex item. In the next example, flex item 1 shrinks 4 times more than flex item 2.

As you can see, the blue flex item consumes 1 spot (100px) and the green flex item consumes 4 spots (400px). How come?

The following code snippet shows the calculation for the available space for the aforementioned example.

// pseudo algorithm for flex-shrink

const flexItem1Width = 500
const flexItem2Width = 500
const flexContainerWidth = 500
// 500 - 500 + 500 = | -500 | = 500px
const spaceToDistribute =
  Math.abs(flexContainerWidth - flexItem1Width + flexItem2Width)
const flexItem1ShrinkFactor = 4
const flexItem2ShrinkFactor = 1
// 5
const totalShrinkValues = flexItem1ShrinkFactor + flexItem2ShrinkFactor
// 100px
const distributionSpot = spaceToDistribute / totalShrinkValues
// 500px - (4 * 100px) = 100px
const flexItem1ComputedWidth =
  flexItem1Width - (flexItem1ShrinkFactor * distributionSpot)
// 500px - (1 * 100px) = 400px
const flexItem2ComputedWidth =
  flexItem2Width - (flexItem2ShrinkFactor * distributionSpot)

Downsizing only happens if required. In the following example, the flex-basis values are respected.

flex-grow

Of course, you can specify multiple flex item properties. The next screenshot shows that providing flex-shrink and flex-grow values is totally legit.

In this case, only flex-grow values take effect causing both flex items to grow equally (because of same factor 1). Obviously, you can also specify different flex-grow values for your flex items and the behavior is exactly as you expect it (same as with flex-shrink but growing instead of shrinking).

Finally, let's take a look at the following example to examine the calculation formula for flex-grow, too.

The algorithm is nearly the same as for flex-shrink.

// pseudo code for flex-grow algorithm

const flexItem1Width = 10
const flexItem2Width = 50
// 10px + 50px - 500px = | -440px | = 440px
const spaceToDistribute = 440
const flexItem1GrowFactor = 10
const flexItem2GrowFactor = 15
// 15
const totalGrowValues = flexItem1GrowFactor + flexItem2GrowFactor
// 440px / 15 = 29,3333
const distributionSpot = spaceToDistribute / totalGrowValues
// 10px + (10 * 29,3333px) = 303,33333px
const flexItem1ComputedWidth =
  flexItem1Width + (flexItem1GrowFactor * distributionSpot)
// 50px + (5 * 29,3333px) = 196,6666px
const flexItem2ComputedWidth =
  flexItem2Width + (flexItem2GrowFactor * distributionSpot)

min-width and max-width

Let's take the last example and specify max-width values for both flex items, too.

As you can see, max-width values are respected. That's why flex item 1 does not grow beyond 100px (it does not scale to 303,333px). In addition, flex item 2 does not scale beyond 200px (it does not scale to 196,6666px).

Finally, let's see how different flex item properties behave.

In this example, flex item 1 cannot consume its hypothetical main size of 600px. Due to the fact that a flex-shrink value other than 0 or auto is specified, the blue flex item is allowed to shrink. However, it does not shrink beyond its min-width value (200px). In the end, its width is 300px and that's because of the properties of flex item 2. The green flex item cannot take its flex-basis width (250px). Due to flex-grow and flex-shrink values the item is allowed to shrink and grow. Growing is not possible because there is no available free space within the flex container. So, the max-width value is irrelevant. However, min-width is respected and the green flex item takes up 200px space.

flex Shorthand

Manuel Matuzovic explains in detail why flex-grow: 1 is not the same as flex: 1.

This is because flex is the shorthand for flex-grow, flex-shrink, and flex-basis. It is tricky because you can use it with one, two, and three values. E.g., if you use only one value, the other values are implicitly set (e.g., by default values).

Summary and Lessons Learned

It helped me a lot to understand scaling of flex items by developing this tiny tool. I can encourage others to do the same for learning purposes and sharing knowledge.

For me, a good understanding of flex-grow, flex-shrink, and flex-basis in combination with known width, min-width, and max-width properties allows for developing better (in terms of responsive and robust) flexbox layouts.

Why Lerna and Yarn Workspaces is a Perfect Match for Building Mono-Repos: A Close Look at Features and Performance

Sebastian Weber — Mon, 18 Mar 2019 22:32:56 +0000

This post is my take on the topic of Mono-Repo. After a brief introduction to Mono-Repos and a comparison with Multi-Repos, I go into tools for establishing Mono-Repos.

I don't want to assess in great detail what repository type is better in which circumstance. However, the goal of this article is all about Mono-Repos and how lerna, npm, and yarn (workspaces) can help. It also makes sense to use these tools in combination. Especially lerna and yarn workspaces can peacefully coexist in a project. How? We will find out in a minute.

What is a Mono-Repo? How does it Compare to Multi-Repo?

Tools like lerna and yarn workspaces have been a decisive factor with the result that managing your codebase in a single repo (a.k.a. Mono-Repo) has gained some traction for about one or two years. A lot of articles were written or conference talks were given about this topic.

In short, a so-called Mono-Repo is a (git) repository that houses multiple projects. Such projects are called workspaces or packages. In contrast, using multiple repositories with each repository housing only one project is called a Multi-Repo approach. Of course, a combination of both approaches is possible. In my current job, we constitute multiple teams where each team has its own repositories. There are teams that pursue a Mono-Repo approach and there are teams believing in a Multi-Repo maxim. Plus, there exists teams leveraging both approaches because the technology, which is part of the repository, is also a factor to have in mind for decision-making (e.g., every Java micro-service is part of an own git repo).

To find out about differences along with pros and cons of Mono-Repos and Multi-Repos, I recommend Markus Oberlehner's article about Monorepos in the Wild.

Tool Landscape for Mono-Repos

A Mono-Repo hosts one or more projects or packages. These packages are "Mini-Repos" that can be versioned, built, and published independently. Therefore, every package contains its own package.json file due to the fact that every package is a full-fledged project on its own.
Packages might have dependency relations between each other. Managing these dependencies are implemented by symlinks.

As we see later, lerna and yarn workspaces give us the ability to build libraries and apps in a single repo without forcing us to publish to npm or other registries. The beauty behind these technologies is that they can find package dependencies by analyzing package.json files located at each project's root folder. Thereby, these tools make it obsolete to manually create symlinks or use "low-level" npm link directly.

This results in faster code-test-debug cycles by sharing components locally. lerna and yarn workspaces together improve the developer experience of managing multiple packages in a Mono-Repo.

Correlation between npm, yarn, yarn workspaces, and lerna

I want to shed some light on the clutter how npm, yarn, yarn workspaces, and lerna are involved in the topic of Mono-repos. Take a look at the following "set diagram".

It depicts three main players and how they correlate. By the way, do not take the proportions too seriously. The diagram's purpose is just to give an impression how things are connected.

npm (marked by 1) and yarn (2) are both native package managers that have many features in common (3). As an example, both leverage the concept of package.json as container for dependency management, which was introduced by npm back in the days. More shared concepts and features are dependency management, publishing, or using lock files to "freeze" dependency versions. There are even more features originated by npm that are also leveraged by yarn, such as publishing to npm registry.

One of the reasons for creating yarn in the first place was performance – it took too long to install dependencies in large projects with npm. Another aspect was missing features, such as a sophisticated concept for freezing versions, offline capabilities, or deterministic behavior in terms of dependency resolution. Though, many of these gaps of npm have vanished over the time and both technologies are more and more feature-compliant nowadays.

Things that still belong solely to npm (1) or yarn (2) are package-lock.json files or yarn.lock files, respectively. However, for us, the application developers, the different implementation of lock files does not really matter. Practically, npm and yarn are even on how version management is handled.

One big feature that is exclusive to yarn is yarn workspaces (4) that was added to yarn about a year ago. It expands yarn by native Mono-Repo capabilities. The next section goes more into Mono-Repo features.

Mono-Repo – What is native? What is user land?

Consider the next diagram depicting how technologies in the Mono-Repo environment are connected to each other.

Marked in red are technologies that provide Mono-Repo capabilities. All of them are based either on npm or yarn. The latter do not provide advanced features for building Mono-Repose besides npm link or yarn link, respectively.

yarn workspaces is the only representative that exposes Mono-Repo capabilities natively. lerna is around for quite some time and came out even before yarn workspaces has existed. lerna provides Mono-Repo features on the level of user land with the help of npm or yarn as dependency management tools.

lerna leverages semantic links for this purpose. It also allows for using yarn workspaces and, then, leaves the whole Mono-Repo aspect solely to the natively implemented features of yarn workspaces. Furthermore, lerna provides sophisticated publishing and version management features to even publish projects independently from each other. Short, lerna offers many features beyond Mono-Repo management. On the other side, yarn workspaces sole purpose is to ease the Mono-Repo workflow. So, you do not have to decide for either side of them. It totally does make sense to use lerna with yarn workspaces.

bolt is a relatively new project that bases on yarn workspaces. Inspired by lerna, its goal is to add more helpful commands on this foundation. However, I do not have any experience with it since I haven't accomplished yet to get bolt up and running in my playground project. In addition, I have realized that there have been relatively few commits lately. So, I do not go any deeper in this article.

Different Variants of Configuring Mono-Repos

This section's goal is to give a quick overview on how to set up the different tools in different variations. You can understand the screenshots as a kind of "cheat sheets". The focus is on the configuration part of the different approaches and how they differ.

I created a small repository to demonstrate the different variants. Just clone the demo project repo and switch branches for the different variants. The README.md file describes how to bootstrap and use (i.e., build and run the dummy app) the particular variant. Another goal of this section and demo project is to provide an easy playground to see the different variants in action from different perspectives: which configuration steps are required, what steps are needed to build and use the sub projects (i.e., packages), how does dependency management work, or what are the timing implications for bootstrapping.

1. Do it yourself

I skip this section but feel free to checkout branch 1-do-it-yourself. Basically you work with npm link and have to create semantic links and install all sub projects manually. I hope you can imagine how tedious and impractical this scenario is for real-world projects.

2. lerna with npm

To get support for automating such manual tasks of approach 1, lerna was introduced. You need a lerna.json file in the root folder. As a convention, lerna uses npm as default.

As you see in the next screenshot, you basically need to edit two files for getting lerna up and running: lerna.json and package.json. Within lerna.json you need to specify where lerna has to look for packages.

To bootstrap all sub projects you need to execute lerna bootstrap by invoking the following npm script:

$ npm run bootstrap

What this command basically does is to go into all packages' root folders and execute npm install. Take a look at the three packages and you will see that lerna caused npm to create a node_modules folder for every package.

3. lerna with yarn

This is the same setup as approach 2. The only difference is that you have to specify yarn as client with the "npmClient" property in lerna.json file. Bootstrapping is also performed by lerna.

What is the difference in contrast to approach 1? Virtually nothing. Mainly it is a matter of taste because the only difference is whether lerna utilizes npm or yarn as dependency manager. The answer to the question, which one to chose boils down to the following questions:

which syntax do I prefer? npm run <command> vs yarn <command>
Should I stick to the quasi-standard or do I like the effort of Facebook
Do I really care about bootstrapping time? If so, take a look at the next chapter which provides some performance benchmarks.

4. yarn workspaces

For this approach, you do not require lerna. yarn workspaces come with built-in Mono-Repo capabilities. To use yarn workspaces you need yarn version 1.0 or higher. As you can see in the following screenshot, you do not need a dedicated configuration file. The package.json file in the root folder needs to be private and has to have a "workspaces" property telling yarn where to find the sub projects (or workspaces in yarn speech).

To bootstrap the project with all its workspaces, you just use yarn since yarn workspaces provides this feature natively:

$ yarn install

or short:

$ yarn

This combines both steps of approach 1 and 2: Installing the dependencies of the root folder and bootstrapping of all packages' dependencies.

One big difference in comparison to approach 1 and 2 is that yarn workspaces creates only one node_modules folder. All dependencies are hoisted to the root folder. Remark: Meanwhile, this behavior is also possible with lerna (without yarn workspaces) by using the --hoist flag.

5. lerna with yarn workspaces

To configure lerna with yarn workspaces you have to have the same configuration in the root's package.json as described in approach 4. However, you need to provide a lerna.json file in the root folder, too. There, you need to tell lerna to use yarn workspaces. Unfortunately, you have to specify the location of the sub projects redundantly in lerna.json. To bootstrap the project, no lerna bootstrap is required, you just have to use yarn install as described in approach 4. It doesn't make much sense to invoke lerna bootstrap since it just calls yarn install itself.

With this setup, lerna completely dedicates the dependency and bootstrapping workflow to yarn workspaces. So, you need to configure more to achieve the same as the previous approach. Why should you then use this way over approach 4? Well, think about this – using lerna and yarn workspaces at the same time makes totally sense. They coexist peacefully together in a Mono-Repo project.

In such a scenario:

You solely use yarn workspaces for the Mono-Repo workflow.
You use lerna's utility commands to optimize managing of multiple packages, e.g., selective execution of npm scripts for testing.
You use lerna for publishing packages since lerna provides sophisticated features with its version and publish commands.

lerna and yarn workspaces

The last section gives a quick understanding on how to set up Mono-Repos with different configurations. This section's focus is more on the features of lerna and yarn workspaces.

yarn workspaces

Up to date, yarn workspaces constitutes the only technology that comes with native capabilities for Mono-Repos. In contrast to lerna, you do not have to execute a separate step for bootstrapping dependencies of the packages. yarn install does the trick by installing the dependencies of the root folder and then for every package.

In contrast to lerna, yarn workspaces does not come with additional features besides dependency management for multi-project setups. Since its foundation is yarn, you have all of yarn's features on hand.

For using yarn workspaces, Facebook has introduced a few additional commands that do only make sense in the context of Mono-Repos.

The following command will display the workspace dependency tree of your current project:

$ yarn workspaces info

The next receipt enables you to run the chosen yarn command in the selected workspace (i.e., package):

$ yarn workspace <package-name> <command>

As an example, with the following command react gets added to the package / workspace called "awesome-package" as dev dependency (instead of --dev you can also use -D):

$ yarn workspace awesome-package add react --dev

Up next is an example to remove a dependency from a particular package:

$ yarn workspace web-project remove some-package --save

If you want to add a common dependency to all packages, go into the project's root folder and use the -W (or --ignore-workspace-root-check) flag:

$ yarn add some-package -W

Otherwise, you get an error by yarn.

With the following command, I add one of my own packages ("awesome-components") to another package ("awesome-app") as dependency. I found out that adding local packages should be done by specifying a version number, otherwise yarn tries to find the dependency in the registry.

$ yarn workspace @doppelmutzi/awesome-app add @doppelmutzi/awesome-components@0.1.0 -D

Using the workspaces feature, yarn does not add dependencies to node_modules directories in either of your packages – only at the root level, i.e., yarn hoists all dependencies to the root level. yarn leverages symlinks to point to the different packages. Thereby, yarn includes the dependencies only once in the project.

You have to utilize yarn workspaces' noHoist feature to use otherwise incompatible 3rd party dependencies working in the Mono-Repo environment. You have to specify this in the project root package.json as you can see in the following example.

// package.json
{
  ...
  "workspaces": {
    "packages": ["packages/*"],
    "nohoist": [
      "**/react-native"
    ]
  }
  ...
}

For more information take a look at the demo project of ConnectDotz.

lerna

As with yarn workspaces, lerna adds Mono-Rep capabilities to a frontend project. However, as described above, lerna operates on "user land" and cannot add such functionality natively.

If you configure lerna to use yarn workspaces then lerna hands over the whole dependency management to yarn workspaces. If you configure lerna with npm or yarn then lerna provides the Mono-Repo capabilities on its own by utilizing symlinks. In such a context, you have to use lerna bootstrap to initialize dependencies of all packages.

John Tucker wrote a great article about using lerna's commands to initialize projects and manage dependencies.

To install react as dependency into all packages, you can use the following command:

$ lerna add react

If you want to install react as dependency only to a particular package, execute the following command:

$ lerna add react --scope my-package

If you have installed react for every package but would like to upgrade/downgrade to a particular version only for a specific package then you can do it like this:

$ lerna add react@16.0.0 --scope my-package

lerna comes with a couple of flags. They constitute options for lerna's sub-commands that need filtering.

Consider the following npm script called "test". The two shell commands below show how to execute testing only on particular packages by using the --scope flag along with globs. lerna tries to execute yarn test for every package that matches.

// package.json
{
  ...
  "scripts": {
    "test": "lerna exec yarn test“
  }
  ...
}

$ yarn test --scope @my-company-services/*

$ yarn test --scope @my-company/web-*

According to the documentation, lerna also provides hoisting shared dependencies up to the root folder just like yarn workspaces' default behavior. Therefore, you have to use the --hoist flag.

$ lerna add react -D --hoist

If you use lerna, a question is whether to choose npm or yarn. As you can see with the "cheat sheets" in the last section, you can switch easily between the different package managers just as you like.

Advanced Frontend Workflow Features and Commands

Even if you pick yarn workspaces for dependency management, it is a good idea to use lerna as well. The reason is that lerna provides utility commands to optimize management of multiple packages. For example, with one lerna command you can iterate through all or particular packages, running a series of operations (such as linting, testing, and building) on each package. Thereby, it compliments yarn workspaces that takes over the dependency management process.

Using lerna for testing or linting from within the root folder is faster than invoking all operations manually from every package folder. John Tucker's blog post deals with testing with lerna in great detail.

Versioning and publishing are important development topics where lerna also shines. lerna allows you to use two versioning modes:

fixed/locked mode: The version of each package can be managed at a single point (in lerna.json file). If a package has been updated since the last time a release was made, it will be updated to the new version. As a consequence, a major change in any package will result in all packages having a new major version.
independent mode: Package versions can be incremented independently of each other. Therefore, the "version" key inside of lerna.json needs to be set to "independent". This approach provides much more flexibility and is especially useful for projects with loosely coupled components.

You can publish packages that have changed since the last release:

$ lerna publish

In independent mode, there exist different options to affect version bumping with the publish command. In addition to use a semver keyword, you can also utilize one of the following version bump flags: from-git or from-package.

The following command publishes to a npm registry while using the conventional commits standard.

$ lerna publish --conventional-commits --yes

The above command also generates change log files. According to lerna's docu, there exist different change log presets, such as angular or bitbucket. By the way, the yes flag skips all confirmation prompts.

Within lerna.json, you can globally define that conventional commits have to be used without using flags:

// lerna.json
...
"command": {
    "publish": {
       "conventionalCommits": true,
       "yes": true
    }
}
...

@jsilvax explains how conventional commits with lerna works and how it can be enforced with commitlint.

Since versioning and publishing are complex topics, the section above shows only a small sample of lerna's possibilities. I do not go more into detail because this would go beyond the scope of this article.

Timing Comparison

One of the main reasons why folks stick to yarn instead of npm is performance in terms of time for installing dependencies. Originally, yarn was developed due to the fact that npm took way too long for installing dependencies (besides the fact that npm had lacked some important features). Meanwhile, npm is available in version 6 and has put a lot of effort to eliminate this gap.

Because you can achieve a Mono-Repo in a variety of ways, let's take a look how these different approaches perform. In the remainder of this section, I present the results of my performance experiment. I cloned the Babel project (approximately in October 2018) because it represents a real-life Mono-Repo with many packages (142 to be precise). Interestingly, the original setup of Babel utilizes lerna with a config that specifies yarn as npmClient (no yarn workspaces) and deactivates yarn's lock file generation.

For every approach (2 – 5) I did the following:

I changed the configuration required for the corresponding approach (i.e., adapt package.json and lerna.json if required).
I measured the elapsed time for installation of dependencies and for a dedicated bootstrapping step (if required).
I measured the time for 3 different use cases. For every use case I performed measurements for 3 times.

The aforementioned use cases (UC) are:

1) I empty npm or yarn cache, I remove all node_modules folders, and I remove all package-lock.json or yarn.lock files.
2) Cache exists, I remove all node_modules folders, and I remove all package-lock.json or yarn.lock files.
3) Cache exists, package-lock.json or yarn.lock files exist, I remove all node_modules folders.

For purging the cache, I executed one of the following commands depending on the used npm client:

$ npm cache clean --force

$ yarn cache clean

As a helper for removing lock files and node_modules folders, I added a script to Babel's root folder called cleanup.sh:

find . -type f -name 'yarn.lock' -exec rm {} +
find . -type f -name 'package-lock.json' -exec rm {} +
find . -name "node_modules" -type d -prune -exec rm -rf '{}' +

Depending on the use case, I eventually commented out the first 2 lines.

For measuring the execution time of the steps for installing and bootstrapping dependencies, I utilized gnomon. The following command constitutes an example for approach 2 (lerna with npm) and UC 1 (empty cache, no node_modules folders, no lock files as precondition) for how I measured elapsed time:

$ npm cache clean --force && ./cleanup.sh && npm i | gnomon && npm run bootstrap | gnomon

Below, you will find the different measurements. I performed these measurements over time, so I have played around with different node, npm, yarn, and lerna versions to find out if different versions have different performance implications.

To switch node and npm versions, I utilized nvm. The following example first installs and uses v9 of node and then installs v5.7.1 of npm.

$ nvm install v9
$ nvm use v9
$ npm i -g npm@5.7.1

Approach 2 (lerna with npm) – Node v10.12.0 / npm v6.4.1 / lerna 2.11.0

UC	Install	Bootstrap	Overall
1	39.1680s	64.7168s	103.8848s
1	40.8052s	78.0730s	118.8782s
1	39.8729s	64.0626s	103.9355s
2	23.9931s	34.8695s	58.8626s
2	23.8788s	38.7979s	62.6767s
2	25.4764s	37.5166s	62.993s
3	16.7291s	35.8081s	52.5372s
3	29.4270s	72.3721s	101.7991s
3	39.4265s	85.0043s	124.4308s

Remark: To be honest, I do not know why the deviations of the last two entries are so high – maybe my Macbook's workload were too high?!

Approach 2 (lerna with npm) – Node v9.10.0 / npm v5.6.0 / lerna 2.11.0

UC	Install	Bootstrap	Overall
1	38.1641s	52.7642s	90.9283s
1	33.3413s	57.4676s	90.8089s
1	32.3160s	52.4869s	84.8029s
2	24.3268s	41.6709s	65.9977s
2	26.4843s	41.6038s	68.0881s
2	29.8368s	43.3759s	73.2127s
3	18.2647s	33.7095s	51.9742s
3	15.2864s	33.4166s	48.7030s
3	15.9295s	34.6834s	50.6129s

Approach 3 (lerna with yarn) – Node v10.12.0 / yarn 1.10.1 / lerna 2.11.0

UC	Install	Bootstrap	Overall
1	36.5181s	58.5693s	95.0874s
1	29.9026s	53.8042s	83.7068s
1	30.8910s	60.2566s	91.1476s
2	15.6954s	34.9247s	50.6201s
2	24.4038s	36.8669s	61.2707s
2	16.1917s	36.4996s	52.6913s
3	9.2134s	29.0799s	38.2933s
3	10.1278s	27.1641s	37.2919s
3	10.2387s	28.1842s	38.4229s

Approach 3 (lerna with yarn) – Node v9.10.0 / yarn 1.10.1 / lerna 2.11.0

UC	Install	Bootstrap	Overall
1	52.3567s	69.5431s	121.8998s
1	45.3363s	56.1238s	101.4601s
1	40.0621s	54.2408s	94.3029s
2	23.2312s	40.1567s	63.3879s
2	22.7905s	39.2331s	62.0236s
2	21.3754s	37.9659s	59.3413s
3	13.4165s	28.6476s	42.0641s
3	13.2283s	27.9781s	41.2064s
3	12.6465s	29.3560s	42.0025s

Approach 4 (yarn workspaces) – Node v10.12.0 / yarn 1.10.1

There is no "bootstrap" step required because yarn install does this under the hood.

UC	Install	Overall
1	34.9199s	34.9199s
1	31.8336s	31.8336s
1	32.6647s	32.6647s
2	17.9583s	17.9583s
2	17.7032s	17.7032s
2	17.9703s	17.9703s
3	12.6103s	12.6103s
3	13.4137s	13.4137s
3	12.8213s	12.8213s

Approach 4 (yarn workspaces) – Node v11.2.0 / yarn 1.10.1

UC	Install	Overall
1	65.1631s	65.1631s
1	69.0633s	69.0633s
1	63.1915s	63.1915s
2	25.6090s	25.6090s
2	22.4050s	22.4050s
2	24.7715s	24.7715s
3	18.0540s	18.0540s
3	18.8891s	18.8891s
3	17.0438s	17.0438s

Approach 5 (lena with yarn workspaces) – Node v11.6.0 (npm v6.5.0-next.0) / yarn 1.12.3 / lerna 3.8.0

With this approach, I try to find out if using yarn workspaces as part of a lerna configuration makes any difference regarding approach 4. Because there is no lerna bootstrap required, the corresponding column is empty.

But as I have expected, there is no difference to approach 4 since lerna is not involved in the dependency installation / bootstrapping process.

UC	Install	Overall
1	60.4779s	60.4779s
1	63.3936s	63.3936s
1	58.1888s	58.1888s
2	32.7976s	32.7976s
2	30.8835s	30.8835s
2	28.9111s	28.9111s
3	16.4637s	16.4637s
3	17.8068s	17.8068s
3	16.3400s	16.3400s

Approach 6 (lerna + npm ci + Audit) – Node v10.12.0 / npm v6.4.1 / lerna 3.4.3

In this approach I use lerna with npm ci that constitutes an alternative for npm install in a continuous integration context. Starting with version 3 of lerna, npm ci is the default for the installation command. However, you can opt-out.

For this approach, package-lock.json files have to exist. node_modules folders should have been deleted, otherwise you get warnings printed out to the terminal. Thus, UC 3 is not possible.

UC	Install	Bootstrap	Overall
1	7.9733s	34.1282s	42.1015s
1	9.3572s	35.0904s	44.4476s
1	8.9436s	36.3684s	45.31200s
2	10.8888s	49.3526s	60.2414s
2	10.9077s	44.9243s	55.8320s
2	11.5785s	43.6369s	55.2154s

Aproach 6 (lerna + npm ci) – Node v9 / npm v5.7.1 / lerna 3.4.3

Using this exact npm version, the npm ci command is available but without the auditing feature. I wanted to test this setup to find out if there are any performance implications without auditing the dependencies. Again, UC 3 is not possible in this scenario.

UC	Install	Bootstrap	Overall
1	9.0732s	29.8326s	38.9058s
1	9.3738s	30.0418s	39.4156s
1	8.8552s	29.1426s	37.9978s
2	11.7469s	39.9573s	51.7042s
2	13.3401s	44.6026s	57.9427s
2	13.3603s	39.9416s	53.3019s

Conclusion

Based on my measurements, I do not see any notable differences between npm and yarn (workspaces) in terms of performance. From a feature point of view, both do not distinguish either. For me, it's a matter of taste which package manager to utilize. Furthermore, they can be swapped anytime or used in conjunction.

Currently, I prefer to use yarn workspaces as Mono-Repo technology because I like its hoisting capabilities. On the other side, this is also possible with lerna and its --hoist flag. In my opinion, yarn workspaces with lerna is a good match: Configure lerna to leave dependency management to yarn workspaces and use its utility commands instead.

Originally published at doppelmutzi.github.io.