This post is for people running into the following error when running a [Protractor](https://www.protractortest.org) test for their Angular apps:

> Error: Error while waiting for Protractor to sync with the page: {}

Many search results on the internet tell you that you can solve it by adding `browser.ignoreSynchronization = true;` to your code, with [a remark like](https://stackoverflow.com/questions/20059943/running-into-error-while-waiting-for-protractor-to-sync-with-the-page-with-basic):

> the key is to browser.sleep(3000) to have each page wait until Protractor is in sync with the project

Unfortunately, this usually is not what you actually want.

## How to solve it

Most of the time, the issue will be that you've added `ng-app` to a different element than the `<body>`, which is where Protractor guesses that your Angular app is located in the page.

You can use a different element, but you will have to tell Protractor which one. You can do so by specifying a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Getting_started/Selectors) referring to the element to the `rootElement` property of your [Protractor configuration file](http://www.protractortest.org/#/api-overview#config-files). A selector that will work most of the time is

```js
  rootElement: '*[ng-app]',
```

In other words, this tells Protractor to find Angular on the element with the attribute `ng-app`.

## Why does _ignore synchronization_ work?
Protractor runs on top of [WebDriverJS](https://code.google.com/p/selenium/wiki/WebDriverJs). WebDriverJS is a Javascript interface that let's you control browsers programmatically, which is useful for e.g. automatic tests.

So then... What does Protractor add? The problem in testing Angular apps using WebDriverJS is that [Angular has its own event loop](https://docs.angularjs.org/guide/scope#integration-with-the-browser-event-loop) separate from the browser's. This means that when you execute WebDriverJS commands, Angular might still be doing its thing.

One could work around this by telling WebDriverJS to wait for an arbitrary amount of time (i.e. 3000ms in the example above) and hope that Angular has settled down during that time. Of course, that wasn't pretty. Thus, Protractor was created to synchronize your tests with Angular's event loop, by deferring running your next command until after Angular has finished processing the previous one.

This is very nice and all, but becomes problematic when you're testing a website of which some pages are written in Angular, and some pages aren't. In the latter case, no matter how long Protractor waits, there is no Angular to complete its cycle -- in which case it will terminate with the error above.

Thus, *for non-Angular pages*, you can tell Protractor _not_ to look for Angular by setting `browser.ignoreSynchronization = true` -- which in practical terms will mean that you're just using WebDriverJS.

So by adding that to your configuration when Protractor cannot find Angular on your page, you're giving up on all that makes testing Angular apps easier than plain WebDriverJS. And yes, adding `browser.sleep` after all your commands will likely work, but it's cumbersome, will break as soon as Angular takes longer than the pause you set, and makes your tests take excessively long.

## The bottom line

- Use the [rootElement](https://github.com/angular/protractor/blob/master/docs/referenceConf.js#L187) property in your Protractor configuration.
- Only use `browser.ignoreSynchronization = true` when testing a page that does not use Angular.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


Error: Error while waiting for Protractor to sync with the page: {}


Git is one of the most important tools in software development right now. It doesn't matter what sector your company is active in, what programming language you use or whether you do waterfall, scrum, kanban or what not; the most common denominator is going to be version control. And most of the time, you'll be using Git to do it.

Unfortunately, knowledge of Git is often limited to [memorising a few commands](https://xkcd.com/1597/) like `git add` and `git commit`, sometimes copy-pasting a `git clone` or a `git pull`, and every now and then finding a StackOverflow answer that spells out the exact command needed to merge, delete a branch, or perhaps even to rebase. And sure, this will get you by most of the time.

Every now and then, however, it will blow up in your face: you might have gotten stuck in a headless state, perhaps you thought a force push was a good idea, or you might mess up some other way. Not pleasant. But what's even worse: **you're likely giving up on Git's best features!** Proper understanding of Git, and the resulting proper workflow, can prevent many programming errors and thus improve the quality of your code. And when problems do slip through the cracks, a clean commit history is excellent documentation for your code, allowing you to more easily spot potential fixes.

# Introducing: A grip on Git

Thus, I wrote [A grip on Git](//agripongit.vincenttunru.com/), a tutorial aimed at those who use Git at a basic level but don't really know what the commands they copy-paste actually do. It's a short read (about eleven minutes) that quickly describes a typical Git workflow, accompanied by a visualisation that displays what happens behind the scenes as you read/scroll. My hope is that this will help people get a better grasp of Git: being able to visualise what is happening should help in remembering what commands you need when working with Git.

Of course, my main goal working on this project was to learn a few new things -- about which I should be able to blog shortly. Nevertheless, I do hope it will be useful to some, as I sincerely believe Git is a very important tool. So [go check it out!](//agripongit.vincenttunru.com/)

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


A Grip on Git: An interactive, visual Git tutorial


One of the reasons I created [A Grip on Git](//agripongit.vincenttunru.com/) was that there were some things with which I wanted to play. One of those things was [Redux](http://redux.js.org/), a library that greatly simplifies state management in your Javascript applications. It helps you to be more explicit about possible changes in your application state by defining all possible state transformations as ([pure](https://en.wikipedia.org/wiki/Pure_function)) functions (referred to as _reducers_ in the Redux documentation).

This has many benefits for you as a developer. One such benefit is that it enables a very cool project called [Redux DevTools](https://github.com/gaearon/redux-devtools). DevTools allows you to undo and redo actions you performed earlier on demand, bringing a running app into the state it would have been in had those actions never happened.

![A showcase of Redux DevTools.](https://i.imgur.com/J4GeW0M.gif)

In A Grip on Git, I wanted to do something similar. As you scroll down the tutorial, Git commands are executed as appropriate to that point in the tutorial. When you scroll back up, however, the visualisation should transform back to the previous state, as if the later commands had never happened. To explain how this works, let's first look at reducers.

## How did reducers work, again?

Reducers are simple functions that take the current state and an action, and return the new state:

```js
(state, action) => newState
```

To keep your app maintainable, it is often advisable to split up your reducers to only concern themselves with parts of the state. For example, you can have a `gitCommands` reducer that can only manipulate `repository` part of the application state, and a `view` reducer that can only manipulate the `view` part of the state:

```js
import gitCommandReducer from 'gitCommandReducer.js';
import viewReducer from 'viewReducer.js';

(state, action) => {
  return {
    repository: gitCommandReducer(state.repository, action),
    view: viewReducer(state.view, action),
  };
}
```

Since this pattern is so common, Redux includes a utility called `combineReducers` with which you can remove the boilerplate. We won't be using that where we're going, though.

## Snapshotting

The reducers demonstrated above stand on equal footing. To enable undoing and redoing, however, we're going to create a reducer that _wraps_ the other reducers, applying to the application state as a whole. This `snapshotReducer` will be active in these three cases:

1. When an action is a Git command, it will keep track of it.
2. When an action is of type `VISIT_SECTION`, and that section hasn't been visited before, it will save a snapshot of the commands resulting in the current state.
2. When an action is of type `VISIT_SECTION`, and that section _has_ been visited before, it will restore the state the way it was when that section was first visited. It will do so by replaying all the actions kept track of in step 1, repeatedly applying the `gitCommandReducer` starting from an empty repository.

The code looks something like this:

```js
// Reducers
import gitCommandReducer from 'gitCommandReducer.js';

// Possible action types
import { GIT_COMMIT, GIT_PUSH } from 'gitCommandActions.js';
import { VISIT_SECTION } from 'viewActions.js';

const snapshotReducer = (state, action) => {
  // Case 1: keep track of Git commands
  if(
    action.type === GIT_COMMIT ||
    action.type === GIT_PUSH
    // etc.
  ){
    const history = state.history || [];
    return {
      ...state,
      ...{
        history: history.concat(action),
      },
    };
  }

  // Case 2: save a snapshot
  if(!state.snapshots[action.sectionName]){
    return {
      ...state,
      ...{
        snapshots: {
          ...state.snapshots,
          ...{
            [action.sectionName]: state.history,
          },
        },
      },
    };
  }

  // Case 3: restore the previously seen state
  if(state.snapshots[action.sectionName]){
    return {
      ...state,
      ...{
        // This is why they're called reducers:
        repository: state.snapshots[action.sectionName]
                    .reduce(gitCommandReducer, {}),
      },
    };
  }
}
```

Now all that's left to do is wrapping the state produced by our original reducers:

```js
import gitCommandReducer from 'gitCommandReducer.js';
import viewReducer from 'viewReducer.js';

(state, action) => {
  return {
    repository: gitCommandReducer(state.repository, action),
    view: viewReducer(state.view, action),
  };
}
```

…with the state as produced by our new `snapshotReducer`:

```js
import gitCommandReducer from 'gitCommandReducer.js';
import viewReducer from 'viewReducer.js';
import snapshotReducer from 'snapshotReducer.js';

(state, action) => {
  return snapshotReducer(
    {
      repository: gitCommandReducer(state.repository, action),
      view: viewReducer(state.view, action),
    },
    action
  );
}
```

## The bottom line

Redux's elegant uncoupling of state management has many benefits. By composing our reducers, we can implement undo/redo functionality _without needing to alter the original reducers_. Likewise, Redux DevTools work on any Redux app regardless of what its reducers do. By wrapping it around your app's reducers, it can keep track of all actions coming in, and replay them using your reducers when necessary.

This is just one of the many ways Redux can improve your life as a developer, so if you haven't tried it yet, I highly encourage you to do so.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


Undo/redo actions by composing Redux Reducers (or: how do the Redux DevTools work?)


André Staltz recently argued that [all Javascript libraries should be authored in TypeScript](http://staltz.com/all-js-libraries-should-be-authored-in-typescript.html) -- which turned out to be rather [controversial on reddit](https://www.reddit.com/r/javascript/comments/4ankfi/all_js_libraries_should_be_authored_in_typescript/). I think that a lot of the resistance originates in the expectation that TypeScript is a completely new language that compiles to Javascript, comparable to the likes of CoffeeScript. In this post I'll try to clear up this misconception.

## It's not a different language?

Of course it _does_ differ from Javascript - not much room for nuance in short and catchy headlines. That said, you could consider the TypeScript compiler to be somewhat like an advanced Javascript linter. You can add it to your build process, and it will tell you when you're doing something in your code you probably did not mean to do. It differs from a normal linter, however, in that you add instructions to your code that help the compiler help you.

## Helping TypeScript help you

Let's say we're writing a Javascript utility library that ensures strings are at least of a certain length by padding them with spaces on the left if necessary. Let's call this utility function `leftpad`. The code might look something like this:

```javascript
function leftpad (str, len) {
  str = String(str);

  var i = -1;

  len = len - str.length;

  while (++i < len) {
    str = ' ' + str;
  }

  return str;
}
```

Typically when publishing a library, you include some documentation on how to use it. In this case, it should mention that the second argument (`len`) should be a number for this function to work.

But while properly documented code is good, self-documenting code is better. It's less work to maintain, and cannot get outdated. Since all valid Javascript is also valid TypeScript, the above code _already_ is valid TypeScript. However, we can also extend it as follows:

```typescript
function leftpad (str, len: number) {
  str = String(str);

  var i = -1;

  len = len - str.length;

  while (++i < len) {
    str = ' ' + str;
  }

  return str;
}
```

(In case it's hard to spot the difference: I added `:number` after the `len` argument.)

When you feed this code to the TypeScript compiler, it will simply strip away `:number`. Before doing that, however, it will check the rest of your code, and warn you when you call `leftpad` with something other than a number for `len`.

## How does TypeScript help your library's users?

If your library's users _also_ use TypeScript, your type annotations enable the compiler to warn them when they pass arguments of the wrong type. Note that the user can still write plain Javascript: simply feeding it to the TypeScript compiler will generate the warnings.

Furthermore, [if their editor supports reading your library's type annotations](http://www.typescriptlang.org/index.html#download-links), it can use those to provide better autocompletion features.

Even without requirements on the tools used by your users, TypeScript libraries have an advantage of being able to generate better documentation. In the past, people tried to [add type annotations using JSDoc](http://usejsdoc.org/tags-param.html):

```javascript
/**
 * …
 * @param {number} len
 * …
 */
function leftpad (str, len) {
  // …
}
```

A significant disadvantage of comments is that they can easily become outdated. With TypeScript, however, your code will fail to compile if the type annotation becomes incorrect. Thus, if you generate your documentation using something like [TypeDoc](http://typedoc.io), your documentation will always include up-to-date type information.

## So: should all Javascript libraries be authored in TypeScript?

Of course not. André, too, simply needed a catchy headline. However, if you're writing a Javascript library, already have a build pipeline, and want to provide a great experience to your library's users, seriously consider adding type annotations in your code. And since TypeScript currently has the largest following, you might as well use that to add them.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


TypeScript is just Javascript



Javascript frameworks come and go -- by the time you have finished reading this post, three new frameworks will have been released. While it may sometimes look like they're just introducing more syntax to learn, the ones that actually get popular often introduce new paradigms that allow us to build features more quickly and with fewer bugs. We can learn a lot by taking a step back: where did we come from, and where are we now, in the year 2016? Which problems do the big frameworks solve, and which are left as an excercise for the programmer?

## At first, there was JQuery

![](/img/A-short-history-of-Javascript-frameworks-a-comparison-of-JQuery-AngularJS-and-React/jquery.svg)

With an easy-to-learn syntax, [JQuery](https://jquery.com/) led to the first bits of interactivity being added to our webpages. If you knew CSS, you knew enough to manipulate your webpage on the client side. Making a button click trigger the addition of a list item would typically look something like this:

```js
$('.button').click(function(){
    $('ol.todos').append('<li>New item!</li>');
});
```

No longer were full page refreshes necessary for every small change, and users rejoiced. That said, this style of programming can quickly become unwieldy. As an example, let's consider that we do not only want to show the new list item to the user, but also to save it somewhere. This requires that we keep an internal model of the list. In turn, whenever the list is modified, both the view and the model will have to be updated:

```js
let todos = []
$('.button').click(function(){
    $('ol.todos').append('<li>New item!</li>');
    todos.push('New item!');
});
```

It's easy to see how quickly this will lead to the introduction of bugs: as soon as the developer forgets to update the view when the model is updated, or vice versa, the user will be looking at incorrect data.

## Enter AngularJS

![](/img/A-short-history-of-Javascript-frameworks-a-comparison-of-JQuery-AngularJS-and-React/angular.svg)

Then, [Angular](https://angularjs.org/) came onto the stage, ushering in the era of actual web applications. It came with strong opinions on how to structure your projects, removing a lot of the error-prone paperwork that we now associate with JQuery. In Angular, your app's components consist of controllers and templates, with the former responsible for manipulating the state of your model and the latter for rendering it to the user. Thus, our little example now looks like this:

```html
<ol ng-controller="TodoListController as vm" class="todos">
    <li ng-repeat="todo in vm.todos">{{todo}}</li>
</ol>
```

```js
function TodoListController{
  let vm = this;

  vm.todos = [];

  vm.addTodo = function(){
    vm.todos.push('New item!');
  };
}
```

Angular eliminated a complete class of bugs: you can safely use `vm.todos`, and it would contain exactly the same list as the one the user is looking at. It quickly grew to be extremely popular, and continues to be widely used to this day.

That said, Angular isn't perfect either. Consider the case where we have two components: a list component, that renders a list of items, and a menu component, that allows the user to navigate through your app.

![](/img/A-short-history-of-Javascript-frameworks-a-comparison-of-JQuery-AngularJS-and-React/todolist.png)

How can we make sure the menu component knows about the number of list items? We can e.g. use the Angular concept of _services_: a single place to store your models, accessible by all your controllers. Our list controller might now look something like this:

```js
function TodoListController(TodoListService){
    let vm = this;

    vm.todos = TodoListService.getTodos();

    vm.addTodo = function(){
        vm.todos.push('New item!');
        TodoListService.updateTodos(vm.todos);
    };
}
```

However, this looks suspiciously similar to the problem we had with JQuery: we are now responsible for keeping things in sync again: the TodoList component's internal model and the service's model. This makes us vulnerable to bugs in which one part of your application displays data incongruous with that in other parts of your application.

An alternative approach would be to have your controllers manipulate the service's model directly. This tight coupling, however, comes with its own set of problems in which changes in one part of your application might have unintended consequences in others.

## React to the rescue

![](/img/A-short-history-of-Javascript-frameworks-a-comparison-of-JQuery-AngularJS-and-React/react.svg)

While Angular remains a popular choice for web applications, an alternative solution has quickly been embraced by a significant number of developers: the combination of [React](https://facebook.github.io/react/) and its trusty sidekick [Redux](http://redux.js.org/).

At the core of the style of programming that characterises this combination is the embrace of _immutable data_. Typically, a React component is merely a function that describes what, _given the state of your application_, your view should look like:

```js
state => view
```

To emphasize: the component does not alter your models (`state`), but merely defines what should be shown to the user (`view`). When our TODO list component is given an array of four items, its render function will return an `<ol>` containing four `<li>`s. When the same list is provided to our menu component, it can return the text `TODOS (4)`.

The advantage of not manipulating your models in your components, is that there is no risk in sharing the models between components. The menu component can safely access the model of the list, since it cannot manipulate it and thus cannot cause inadvertent effects in the list component. When the model is changed, the rendering function is simply called again with the updated model, and React makes sure that the new view will be displayed to the user.

Every component now always has access to an up-to-date version of our models, and so does our view. Redux helps you managing updating your models. You define the possible actions a user can perform, and a function that describes how those actions affect the state:

```js
(currentState, action) => newState
```

Again, note that this function uses immutable data: it does not modify `currentState` or `action`, but simply returns a new object `newState` that describes what the state should look like given the previous state and the action that was performed. (Apart from safe state sharing among different components, this also enables [other cool features](https://vincenttunru.com/Composing-Redux-reducers/).)

## What's next?

By taking a birds-eye view of the history of Javascript frameworks, we've seen what each brings to the table, and what problems they solve. Angular largely removed the need to keep your views and models in sync, and React/Redux gives us the ability to safely share our models between our components, while maintaing a proper separation of concerns.

While the idea of learning so many frameworks can be a bit too daunting, simply being aware of the new paradigms they bring to the table can go a long way. While React has seen rapid adoption, Angular is still going strong; thus, you can simply stick with Angular if you're comfortable with that. Nonetheless, the lessons taught by React can help be carried over to Angular, and are thus still useful to study.

No framework is perfect, and neither is React. In [my next post](https://vincenttunru.com/Javascript-reactive-programming/), I will look at a remaining pain point, and what trend is emerging to deal with it.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


A short history of Javascript frameworks: a comparison of JQuery, AngularJS and React



Previously, [I took a look at the current state of Javascript frameworks](https://vincenttunru.com/2016-javascript-framework-overview/). Today, I will take a look at what I think will be the next frontier of front-end programming: functional reactive programming.

## (Functional) Reactive Programming

Reactive Programming revolves around the use of a data structure representing asynchronous data, called _observables_ or _streams_. You could compare them to [Promises](http://www.html5rocks.com/en/tutorials/es6/promises/).

![A promise returning the value 3](/img/Javascript-reactive-programming/promise.png)

(Diagrams are courtesy of [RxMarbles.com](http://rxmarbles.com). The arrows represent time.)

Roughly speaking, promises represent a value that might not be known when they are first used, but might arrive any moment. Observables are similar, except that they represent the potential arrival of multiple values.

![An observable returning the values 1, 2 and 3, in that order](/img/Javascript-reactive-programming/stream.png)

Observables are great for representing related values arriving asynchronously, such as characters entered into an input field.

When we use functions that take observables as input and produce a new observable as output (i.e. [pure functions](https://en.wikipedia.org/wiki/Pure_function)), we are doing what is commonly referred to as _Functional Reactive Programming_. There are many Javascript libraries providing commonly used operators, such as [RxJS](https://github.com/Reactive-Extensions/RxJS), [Bacon.js](https://baconjs.github.io/) and [Kefir](https://rpominov.github.io/kefir/).

These can be simple operators like [`delay`](http://rxmarbles.com/#delay), that simply returns a new stream that produces the same values as the input stream, only with a slight delay.

![Example of `delay`](/img/Javascript-reactive-programming/delay.png)

The operators might use the actual values produced like [`map`](http://rxmarbles.com/#map), which returns a new stream that produces the values of the input stream after being passed through a given function.

![Example of `map`](/img/Javascript-reactive-programming/map.png)

Previous values could also be used, like in [`scan`](http://rxmarbles.com/#scan), which produces an accumulator using a given function (similar to the [`reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce) function you might know already).

![Example of `scan`](/img/Javascript-reactive-programming/scan.png)

They might even combine multiple streams like [`merge`](http://rxmarbles.com/#merge), which returns a stream that produces all the values produced by its input streams.

![Example of `merge`](/img/Javascript-reactive-programming/merge.png)

One you get used to them, observables can greatly simplify dealing with asynchronous data. For example, consider a situation where you have two input fields, and you want to check whether both of them have a value. When you have observables `field1$` and `field2$` (convention is to denote observables by appending a `$`), you can use RxJS to create a stream that emits a new boolean every time the form changes validity:

```js
const isValid$ =
  Rx.Observable.combineLatest(field1$, field2$)
  .map(fields => fields.every(field => field.length > 0));
```

(You can see it in action in [this fiddle](https://jsfiddle.net/vhb4jcw9/).)

This might be difficult to parse the first time you read it, but once it clicks, working with asynchronous data becomes far easier with observables in our toolbox. Note that the above approach easily scales to however many form fields you have.

An additional benefit is that it steers you away from a whole class of bugs. To illustrate: consider trying to do the above using a more traditional approach. We would likely [create an event listener to check the validity of the form](https://jsfiddle.net/tn32yvmm/) when the user enters input:

```js
function checkValidity(){
  return document.getElementById('field1').value.length > 0 &&
         document.getElementById('field2').value.length > 0;
}
```

We wouldn't be the first to attach the event listener to the final form field and be done with it. We fill in the form, see the validity update, and conclude that it works. After deployment, however, some users will fill out the form, and then go back to the first field and clear its contents. Surprise: our form will still claim that it's valid. We forgot that the event handler also had to be attached to the other form field.

Obviously, what with you being the perfect programmer, this wouldn't happen to you. But by using observable, such errors would be really easy to spot. When your less gifted colleague adds is tasked with adding a form field, there's only one place it needs to be added: the combined form stream. It will then just work, validation included, as the data flows directly from the form fields into the validation.

There is much more to Functional Reactive Programming than this, and fully wrapping your head around it might take some time. If you're interested, you might want to try [Getting Started with RxJS](https://github.com/Reactive-Extensions/RxJS/tree/master/doc#getting-started-with-rxjs).

## FRP today

If you're as excited about FRP as I am, you're in luck: it's already gaining a lot of headway.

Consider, for example, the combination of React and Redux I touched upon in [my previous post](https://vincenttunru.com/2016-javascript-framework-overview/). With Redux, you describe how your application's state evolves in response to user actions with a function of the form `(currentState, action) => newState`. You then use React to describe what view that state should result in with a function of the form `state => view`.

Wait a minute... If you squint hard enough, that looks just like manipulating an observable with the [`scan()`](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/api/core/operators/scan.md) and [`map()`](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/api/core/operators/select.md) methods!

![React/Redux's architecture modelled](/img/Javascript-reactive-programming/react_architecture.png)

This is a very limited reactive system. In essence, all asynchronous input to your application will have to be converted to that one observable for actions. This can get quite awkward for asynchronous input that isn't exactly a user action, such as HTTP requests. This often leads to workarounds such as [emitting multiple actions](http://redux.js.org/docs/advanced/AsyncActions.html), e.g. one when a request is sent, and another when the response comes in. [Several libraries have arisen](https://twitter.com/dan_abramov/status/689639582120415232) that claim to make it easier, but all of them are bound to that single stream.

A Redux alternative called [MobX](https://mobxjs.github.io/mobx/) is also gaining ground, providing an implementation of observables to model component state. I haven't looked into it too deeply yet, but it appears to distinguish itself from Redux mainly by enabling components' local state to be modelled as observables as well, whereas Redux only supports a single place to hold all your application state.

On the Angular side, the developers have decided to [endorse and use RxJS](https://angular.io/docs/ts/latest/guide/server-communication.html#!#rxjs) for the major rewrite that they are currently completing. They're using it for HTTP requests, the planned router [is using it as well](http://blog.thoughtram.io/angular/2016/06/14/routing-in-angular-2-revisited.html), and you can pass them to your view templates [for more efficient rendering](http://victorsavkin.com/post/110170125256/change-detection-in-angular-2). That said, user input is still handled through callbacks, and in practise, many Angular apps will likely apply none or few transformations on their observables before passing its values back to regular callback- and promise-based code.

## A glimpse of the future: Cycle.js

The first steps toward wider adoption of FRP have been taken, and they don't seem to be stopping any day soon. So where will this bring us?

One framework that is worth looking into in this regard is [Cycle.js](http://cycle.js.org/). Cycle applications are conceptually simple: all they do is convert a series of input streams (_sources_, in Cycle terminology) to a series of output streams (_sinks_). These input streams are provided by what Cycle dubs _drivers_, and the output streams are fed back into those drivers. The values emitted to the output streams are descriptions of the [side effects](https://en.wikipedia.org/wiki/Side_effect_(computer_science)) you want to happen, and the drivers actually execute them, looping potential results back into the input streams. These drivers are usually small, separate libraries tailor-made to perform a specific side-effect in response to incoming observables, and to deliver any potential outside values through observables as well. A consequence is that the app itself is side-effect free, making it easy to reason about and easy to test.

Let's illustrate this with a very simple example application.

![](/img/Javascript-reactive-programming/cycle_lifecycle_app.png)

To be able to show something to the user, we output a description of what we want the DOM to look like onto the DOM driver's output stream. The DOM driver will then apply those changes to the DOM.

![](/img/Javascript-reactive-programming/cycle_lifecycle_render.png)

Likewise, the DOM driver also provides input streams that contains user input. Which can, in turn, be a trigger to push new DOM descriptions onto the output stream and thus update the view.

![](/img/Javascript-reactive-programming/cycle_lifecycle_input.png)

User interaction is only one type of side effect though. Another commonly used driver is the HTTP driver. By pushing values onto the output stream to the HTTP driver, apps can send HTTP requests, and the accompanying responses will be pushed onto the corresponding input stream.

![](/img/Javascript-reactive-programming/cycle_lifecycle.png)

The DOM and HTTP drivers are just the tip of the iceberg. There are plenty more drivers imaginable, such as the [history driver](https://github.com/cyclejs/history) for the browser's [History API](https://developer.mozilla.org/docs/Web/API/History_API), a [storage driver](https://github.com/cyclejs/storage) for interacting with [localStorage](https://developer.mozilla.org/docs/Web/API/Window/localStorage), [and more](https://github.com/cyclejs-community/awesome-cyclejs#drivers). Of course, you can also [write your own](http://cycle.js.org/drivers.html).

## Wrapping up

As we saw, the combination of observables and functional programming principles can greatly simplify working with asynchronicity such as often abundant in web applications, and that is still difficult to deal with in [the current crop of Javascript frameworks](https://vincenttunru.com/2016-javascript-framework-overview/). It's been getting more and more uptake as React developers slowly get familiar with a reactive programming style, and Angular developers set to have the full power of RxJS available in version 2. Cycle.js shows, however, that observables can be used far more extensively, for all that is asynchronous, in an elegant application architecture.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


Up-and-coming: Reactive programming in Javascript


Here's a short public service announcement for those who write their tests using [Jasmine](https://jasmine.github.io/) or [Protractor](http://www.protractortest.org/): avoid [the `toBeTruthy()` and `toBeFalsy()` matchers](https://jasmine.github.io/2.5/introduction.html#section-Included_Matchers) and use `toBe(true)` and `toBe(false)` instead.

(Off topic: I've also seen people confuse Jasmine and [Karma](https://www.npmjs.com/package/karma). Karma fires up a browser to run tests in, but the actual tests are written using a testing library such as Jasmine.)

![](/img/toBeTruthy-vs-toBe-true/no_toBeTruthy_allowed.svg)

# What's the problem?

I've seen people using these matchers assuming they're just a weird spelling of `toBeTrue()` and `toBeFalse()`. But they're not: truthy and falsy [refer](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) to values that are evaluated to `true` and `false` _after being [coerced](https://developer.mozilla.org/en-US/docs/Glossary/Type_Conversion) to a boolean_!

So yes, `true` is truthy, but `42` is _also_ truthy, and even `[]` and `'false'` are truthy! In fact, everything that is not `0`, `""`, `null`, `undefined`, `NaN` or `false` is truthy.

This means that if you're testing a function that errorenously returns `'false'` (a string) instead of `false` (a boolean), `toBeTruthy()` will match and `toBeFalsy()` will not.

So just like [you should never use `==`](http://eslint.org/docs/rules/eqeqeq), try to avoid `toBeTruthy()` and `toBeFalsy()`.

# So then what should I use?

Just use [the plain old `toBe()`](https://jasmine.github.io/2.5/introduction.html#section-Matchers) matcher to check for a value `toBe(true)` or `toBe(false)`, respectively. Unless you actually want your function to return different types of values, but even then I'd recommend you to change your code: otherwise, everywhere you're calling that function, you have to check for all possible return types.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


toBeTruthy() will bite you — use toBe(true)


There's a lot of excitement about reactive programming in the front-end community:

- Angular [ships](https://angular.io/docs/ts/latest/guide/server-communication.html#rxjs-library) RxJS with Angular 2
- There's a [draft proposal](https://github.com/tc39/proposal-observable) to add an Observable to Javascript proper
- There's [a framework](https://cycle.js.org/) built entirely around the Observable
- React is most commonly used in [a reactive application structure](https://vincenttunru.com/Javascript-reactive-programming/#frp-today) together with [Redux](http://redux.js.org/)
- …and if not with Redux, then with the Observables of [MobX](https://mobxjs.github.io/mobx/)

Reactive programming is everywhere, so it's time we took a look at its primary concept: the Observable. What problems does it solve for us?

To answer this question, I will present three different metaphors that highlight situations that Observables can deal with elegantly. After this article, you should have a good idea of when to use Observables, and for what.

## Metaphor 1: Observables as special Promises

A [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise) is a data structure that represents a value that might not be immediately available. This is very useful when you want to perform some action as soon as that value does become available. An example use case is when you have made an HTTP request: at a certain moment, the response is going to come in, at which point you will want to perform some action. A Promise can then represent that eventual response.

A Promise could be described as such:

![A long arrow pointing to the right. At the far end at the right-hand side, a circle labeled "3" is located on the arrow, on top of a vertical line.](/img/3-metaphors-that-show-the-power-of-the-Observable/promise_marbles.png)

The arrow represents the passage of time; at a certain point, the promise is resolved with the value `3`.

### What can Observables do for me?

A Promise is useful if you're waiting for a single value, and want to perform an action when that value comes in. But what if you're waiting for multiple values? For example, what if you're waiting for user input, where you're waiting for multiple keypresses that drip in one by one?

This is where Observables come in. They can be seen as _Promises that can return multiple values_:

![A long arrow pointing to the right. On top of the arrow are, from left to right, three circles labeled "1", "2" and "3", respectively, followed by a vertical line.](/img/3-metaphors-that-show-the-power-of-the-Observable/observable_marbles.png)

The above is an Observable that, at different moments in time, delivers the values `1`, `2` and then `3`. Some time after that, it "completes": no more values are to be expected. This is indicated by the vertical line.

## Metaphor 2: Observables as a Design Pattern

Design Patterns are best practice approaches to common problems in software design. For example, the _Iterator_ pattern is a common approach to dealing with containers with multiple elements, e.g. lists of users. Your code can use an Iterator to get access to the container's elements, without needing to care about the container's implementation. 

![Schematic representation of an Iterator: a block of code with three arrows pointing to an Iterator. The arrows represent method calls to access elements from the container.](/img/3-metaphors-that-show-the-power-of-the-Observable/iterator.png)

Likewise, the _Observer_ pattern is a common approach when you have code that needs to become active when something happens elsewhere in the code. In this pattern, your code (the Observer) can register itself with a Subject, which will then notify it when the change has occurred.

![Schematic representation of an Observer: a block of code (the Observer) with an arrow pointing to it from a Subject. The arrow represents a method call on the Observer to notify it of an update.](/img/3-metaphors-that-show-the-power-of-the-Observable/observer.png)

### What can Observables do for me?

Whereas an Iterator is useful when you have a container with multiple elements readily available, an Observable shines when these elements might not yet be available. For example, when you need to call several REST APIs to collect all profile data related to a user, the different elements of the profile might arrive at different moments. Using an Observable, you can construct the full profile as the data rolls in.

Observables can be seen as a combination of the Iterator pattern and the Observer pattern. Whereas the Iterator is _pull_-based (your code "pulls" values out of the Iterator), an Observable is _push_-based: the Observable "pushes" values to your code as they arrive. 

![Schematic representation of an Observable: a block of code with three arrows pointing to it from an Observable. The arrow represents method calls on your code to provide it with new elements as they arrive.](/img/3-metaphors-that-show-the-power-of-the-Observable/observable.png)

## Metaphor 3: Observables as a way around shared mutable state  

Consider two functions that increment and decrement a counter, respectively:

```js
let counter = 0;

function increment(){
  counter++;
}

function decrement(){
  counter--;
}
```

In this example, both functions (shared) can change (mutable) the value of `counter` (state). This setup has some disadvantages, the most important of which is that it can make your code hard to follow. For example, you cannot simply look at the `increment` function in isolation: you have to keep track of every line of code that refers to `counter` and keep in mind how they can affect the function's code and vice versa. In the toy example above this is not a problem, but as your codebase grows, your code will become harder and harder to maintain.

A common approach to deal with this is to write your functions in a way that they do not depend on anything outside that function — so-called _pure_ functions. Rather than relying on the application being in a certain state, everything the function needs will have to be passed in as an argument. This results in functions that look like this:

```js
function increment(previousValue){
  return previousValue + 1;
}

function decrement(previousValue){
  return previousValue - 1;
}
```

The question then is: how we can know what the present value of the counter is, e.g. to show it to the user? You could store it in a variable which could then be updated like this:

```js
let counter = 0;
counter = increment(counter);
```

…but then we're back in the land of mutating state! If we want to show this value to the user, we still have to be aware of every line of code that references `counter` and might require updating the view.

### What can Observables do for me?

Observables provide a way to deal with changing values without having to resort to shared mutable state. Instead, you explicitly describe the way the value can change using pure functions. So to take our use case of showing the counter value to the user, we could simply subscribe to an Observable that delivers the new value of the counter as it changes, and use that to update the view.

![An application window showing a 3, the current value of the counter. An arrow pointing to the window is delivering the new values 2, 1 and 2, respectively.](/img/3-metaphors-that-show-the-power-of-the-Observable/mutation.png)

Let's say we have two buttons for incrementing and decrementing our counter, respectively:

```html
<button type="button" id="increment">Increment</button>
<button type="button" id="decrement">Decrement</button>
```

An Observable delivering the value `1` everytime the Increment button would look like this:

```js
const incrementClick$ =
  Rx.Observable.fromEvent(document.getElementById('increment'), 'click')
  .map(ev => 1);
```

Likewise for decrementing, but with the value `-1`. An Observable delivering counter values would then be constructed as such:

```js
const counter$ =
  // Create an Observable delivering 1 and -1 on
  // their respective button clicks:
  Rx.Observable.merge(incrementClick$, decrementClick$)
  // Emit a 0 before any button is clicked:
  .startWith(0)
  // Then add whatever is emitted (1, -1 or 0) to
  // whatever we had before:
  .scan((accumulator, value) => accumulator + value);
```

You can then subscribe to that Observable to update the view with the latest counter value:

```js
counter$.subscribe(counter => {
  document.getElementById('counter').innerHTML = counter.toString();
});
```

(You can view [the full working example at JSFiddle](https://jsfiddle.net/43me829w/).)

It should be noted that there are nothing but pure functions in the above example. There is no explicit variable holding the state, yet we are still able to display a dynamic counter value.

## What's next?

We've seen three different metaphors that helps us think about Observables:

- As Promises that can return multiple values
- As a Design pattern for containers that will have multiple elements, eventually
- As a way to represent mutable values without requiring shared mutable state

These metaphors provide insight into how Observables can be useful. As a next step, I'd recommend reading up on what you can do with Observables, and how they can help you structure your application. Coincidentally, I've written [another article](https://vincenttunru.com/Javascript-reactive-programming/) that deals with exactly that!

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


3 metaphors that show the power of the Observable



This post is a summary of a talk I gave today, in which I made the case for Functional Reactive Programming in Javascript using libraries such as [RxJS](http://reactivex.io/rxjs/).

## Bugs, bugs, bugs

> If debugging is the process of removing bugs, then programming must be the process of putting them in. —Edsger W. Dijkstra

All else being equal, software with fewer bugs is better than software with more bugs. To minimise the amount of bugs we ship, we spend a considerable amount of effort on debugging. A more time-efficient way of achieving this same goal, of course, is to prevent us from writing these bugs in the first place.

To find out how we can avoid writing bugs, let's consider what a bug is: software doing things the programmer did not expect it to do. In other words: the harder it is for us to understand the code we work on, the more likely it is to contain bugs.

So what makes our code hard to follow? Consider the following example code:

```js
let counter = 0;

function increment(){
  counter++;
}

function decrement(){
  counter--;
}
```

It looks rather innocent: we have a counter with an initial value of 0, and the functions `increment` and `decrement` to respectively increase and decrease its value by 1. It exhibits a problematic property described by three words: **shared mutable state**.

In short, the _state_ of the application is located in `counter`, which holds the current value of the counter at any point during the lifetime of the application. Both functions _share_ access to `counter`, and both can modify ("_mutate_") its value.

Looking at the code above, my earlier claim that this is hard to follow seems absurd. Consider, however, any non-trivial codebase, where functions consist of more than one line, and `increment`, `decrement` and `counter` might all be located in different files. In that case, anyone who wants to edit either of those will have to keep the rest of the codebase in mind, because bugs might be lurking there when you modify the code here.

## Our saviour: pure functions

The way around this is by using _pure functions_: functions that do not modify anything outside of themselves (in other words: they don't rely on _side effects_). Instead, they receive everything they need as input, apply some transformations, and provide the result as output. With this in mind, the `increment` function might receive a number representing the current counter value, and return a new number that is 1 higher than that:

```typescript
function increment(counter){
  return counter + 1;
}
```

And of course, likewise for `decrement`.

So how would we use functions written in this way? Well, rather than simply calling the function and hoping for something to happen, we have to pass it the correct input and then use the output to update the counter:

```js
let counter = 0;
counter = increment(counter);
```

But of course, this is not what we usually do. Rather, we increment the counter in response to e.g. the user clicking a button. So we'd actually write a handler for the click event:

```js
let counter = 0;

function onClick(){
  counter = increment(counter);
}
```

…but now we're back in the land of shared mutable state: `onClick` changes a value outside of its own scope! Does this mean we're stuck now? Of course not!

## Functional Reactive Programming to the rescue!

Using the principles of Functional Reactive Programming, we can write the largest part of our application using nothing but pure functions. We can do so by pushing side effects to the "edge" of our application, where it interacts with the "outside world", such as responding user input or receiving HTTP responses. We convert those into Observables as soon as possible, [which we can manipulate using nothing but pure functions](https://vincenttunru.com/3-metaphors-that-show-the-power-of-the-Observable/#metaphor-3-observables-as-a-way-around-shared-mutable-state).

For our counter example, this would look somewhat like this:

```js
// Convert user input to Observables
const incrementButton = document.getElementById('incrementButton');
const decrementButton = document.getElementById('decrementButton');

const incrementClick$ =
  Observable.fromEvent(incrementButton, 'click');
const decrementClick$ =
  Observable.fromEvent(decrementButton, 'click');

// Convert this input to an Observable producing counter values,
// using nothing but pure functions
const counter$ =
  Observable.merge(
    incrementClick$.map(() => 1),
    decrementClick$.map(() => -1)
  )
  .startWith(0)
  .scan((accumulator, value) => accumulator + value);

// Subscribe to counter values, and display them to the user
counter$.subscribe(counter => {
  document.getElementById('counter').innerHTML = counter.toString();
});
```

As you can see, we need a few lines of side effects at the top and bottom where we deal with the outside world. The meat of our application, however, consists only of pure functions that do not share state. The challenge here is to [understand Observables](https://vincenttunru.com/3-metaphors-that-show-the-power-of-the-Observable/), but once you've got that down FRP code is relatively easy to follow. Which means we'll write fewer bugs!

(And that's even without considering how easy it is to write unit tests for pure functions.)

## Summing up

As we saw, code that is hard to follow has more bugs. Code becomes hard to follow when it contains shared mutable state. Pure functions avoid this, but it can be a challenge to use them extensively.

That is where Functional Reactive Programming comes in. FRP allows us to represent changing state, while allowing us to keep (most of) our application logic pure.

If this captured your interest, I would encourage you to [read more about Functional Reactive Programming](https://vincenttunru.com/Javascript-reactive-programming/).

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


The case for Functional Reactive Programming


Version control systems like Git are widely appreciated for their ability to provide a centralised location for source code, for helping people work together on the same code base, and for allowing you to scrap the crap you just wrote and get your code back to the state it was in before you started your misguided refactoring.

However, there's one thing it can do for you that is overlooked too often: help you **document your code**. In fact, it can prove to be at least as useful as comments.

Let me show you why.

## What commits can do for you

An important tool in Git is [`git blame`](https://www.git-scm.com/docs/git-blame). Apart from telling you which blockhead introduced an especially ill-conceived piece of code (you, a month ago), it also allows your editor to provide a lot more context to your code. For each line of code, it not only lists the author, but also the commit that last touched it.

Thus, your editor can show the commit messages associated with each line, providing more guidance on why it was introduced. It can tell you why a configuration option was set to a specific value. And in contrast to regular comments, commit messages are directly linked to the version of the code they apply to, so they will never become outdated.

![](/img/Commits-are-documentation/annotations.png)

You can also inspect each commit to find out which _other_ lines were changed, in which files, at the same time. Since most behaviour can only be implemented by modifying your code in multiple places, it often helps to see those changes together to understand why they were needed. And if you see a stray comment that no longer makes sense, its commit will often tell you what was actually meant.

A commit can also serve as documentation on how to achieve a certain task. For example, I recently converted this blog from [Hexo](https://hexo.io/) to [Jekyll](https://jekyllrb.com/) (my apologies if you are subscribed to [my feed](https://vincenttunru.com/atom.xml) and saw duplicate posts). By referring to [a single post's migration commit](https://gitlab.com/VincentTunru/blog/commit/dae75d6efc7d88503bf0d5d3f6a9750d27f2199b), I could see exactly what steps were needed to migrate a post — and which step I forgot when one of them didn't show up properly. Apart from being useful as a reference for yourself, this can also be helpful in instructing other contributors: "to add a new endpoint to the API, take a look at this commit for inspiration".

## Crafting your commits

The above is very useful, but it works best if you invest at least _some_ effort into your commits. 

This means that you put some thought into your commit messages and how they document your changes. Make sure they are descriptive enough, that they still make sense a week from now, and that you list any trade-offs you might have had to make — although you might also want to accompany this with a comment to that effect.

[![](https://imgs.xkcd.com/comics/git_commit.png)](https://xkcd.com/1296/)

It also means that you think about what to include in a commit: does it make sense to see these changes together? There's a reason Git has the concept of a [staging area](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics#_the_three_states): it is not necessarily the case that all changes in your working directory make sense in the same commit. As an added bonus, this also makes it more feasible to [revert](https://git-scm.com/docs/git-revert) faulty work.

So basically, try to avoid `git commit -am "asdf"`, and commit consciously. Unless, of course, there's an emergency.

![In case of fire: `git commit`, `git push`, then leave the building.](https://raw.githubusercontent.com/louim/in-case-of-fire/d4f070b18b3d1f416e93762f98507f84708af93a/in_case_of_fire.png)

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


Spend effort on your Git commits


When it comes to unit testing, there are three schools of thought that I'm aware of:

1. We don't do unit testing, since they are overrated/too hard/take too much time/whatever.
2. We only test critical/error-prone parts of our code, and bugs that have been fixed.
3. We want a significant part of our code to be covered by tests.

I'm usually in the latter camp: I think that automated tests are one of the most effective ways to ensure code quality on a long-running project.

This strategy, however, is often accompanied with a policy of maintaing at least a certain level of code coverage. And since there are usually some parts of the codebase where the effort required to bring them under test is considered not to outweigh the benefits, unit test policies usually stipulate a minimum amount of code coverage of 80%, 90% or 95%.

I'd like to argue that best practice is to require code coverage analysis to report a coverage of 100%.

## Why not <100%

> When a measure becomes a target, it ceases to be a good measure.

—[Goodhart's Law](https://en.wikipedia.org/wiki/Goodhart%27s_law)

The risk of _requiring_ a certain level of coverage is that achieving that level becomes the goal, instead of the goal being to write proper tests. And what is the easiest way to achieve 80% code coverage? Simple: write tests for the 80% of your code that is easiest to test.

However, you do not want to test the code that is _easiest_ to test: you want to test the code that is _most important_ to test. In other words: whether a certain line of code is worth the effort of writing a test should be consciously decided, rather than certain parts not being tested simply because the other parts were enough to achieve the required coverage metrics.

## Reaching 100% without losing your mind

Code coverage reports should offer guidance, not a goal to meet. More specifically, they can help you find out which parts of your code you actually forgot to test. It regularly happens that there are some unhappy paths that I did not think of when writing tests, but of which it was obvious that they would need to be dealt with when writing code. When anything below 100% coverage is configured to be insufficient, my testing tools will then point out to me that those parts still need a test.

Of course, it is still likely that there are parts of your code for which the benefits of testing do not outweigh the costs. However, rather than lowering my coverage target by some arbitrary number, I [mark those parts as irrelevant for the coverage report](https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md), _with a comment explaining the reasoning behind not testing it_.

In other words: I don't want 100% my code to be covered by unit tests, but I at least want 100% of my code _to have been considered_ for unit tests. That way, what to test is still left to the programmer's best judgment, and code coverage analysis becomes helpful rather than yet another tool to satisfy.

Now, I haven't seen the above mentioned as best practice before, so I'm very much interested in what people have to say about it. That said, regardless of the testing strategy you use, I think developer buy-in is always a good starting point. The tooling we use should help us achieve our goals, rather than set them for us.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


If you measure test coverage, aim for 100%


I just implemented a little change that I think will greatly improve the quality of bug reports I receive: I created a minimal boilerplate repo for my project.

The best bug reports are [minimal, complete, and verifable](https://stackoverflow.com/help/mcve). In other words:

- The maintainer should not be distracted by things not relevant to the bug.
- All info relevant to the bug should be included.
- The maintainer should be able to observe the buggy behaviour by themselves.

Submitting a high-quality bug report is not always easy though, which can often lead to it not being worth the effort to report. Consider, for example, a package I maintain: [`wdio-webpack-dev-server-service`](https://www.npmjs.com/package/wdio-webpack-dev-server-service). To create a minimal, complete and verifiable example for a bug report, you would have to:

- create a barebones Webpack project
- set up WebdriverIO and add a minimal test
- set up wdio-webpack-dev-server-service
- and of course: reproduce your bug

That's _three_ tools to configure! And since it's probably been a while since you've set up those tools for your own project, that's three tools for which you'll have to dig up the documentation again.

To save my users the effort and thus hopefully encourage high-quality bug reports, I created [a repository with a barebones project](https://gitlab.com/Vinnl/wdio-webpack-dev-server-service-minimal-repro). The repository contains all the boilerplate and instructions needed to get `wdio-webpack-dev-server-service` up and running. I then updated the issue template to refer to that repository and to encourage bug reporters to use it to create a minimal, complete, and verifiable example.

Now bring on those bug reports.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


Towards better bug reports


_Create React App_ 2.1.0 just arrived [with TypeScript support](https://github.com/facebook/create-react-app/releases/tag/v2.1.0)! While [Will Monk](https://twitter.com/willmonk)'s fork [_create-react-app-typescript_](https://github.com/wmonk/create-react-app-typescript/) has served us well, being able to use the official version has a number of advantages. Most importantly: it is supported by the full weight of the Create React App team, and will therefore stay closely aligned with React proper and will always have up-to-date documentation. Furthermore, you are able to use everything that is supported by Create React App, like [Sass](https://sass-lang.com/).

The implementation also deviates a bit from create-react-app-typescript's. Most importantly, TypeScript is only used for type checking, whereas transpilation is done by [Babel](https://babeljs.io/). The disadvantage of this is that you are behest to the caveats of [Babel's TypeScript support](https://blogs.msdn.microsoft.com/typescript/2018/08/27/typescript-and-babel-7/), most notably the lack of namespaces and having to use the `x as Foo` type casting syntax. In practice, however, it is unlikely that these caveats will affect a React app, and the upside is that you are now able to tap into Babel's extensive ecosystem.

So great: we can now use TypeScript for new apps created with Create React App. However, many of us already have apps written using create-react-app-typescript. How much work is it to port those to Create React App proper?

As it turns out: not that much. Let's get to it.

## Step 1: remove react-scripts-ts, add react-scripts

Create React App is a command line application that generates a basic React application for you, but instead of adding all commonly used dependencies directly, it adds a single dependency that bundles them and is maintained by the CRA team itself: `react-scripts`. Likewise, create-react-app-typescript has its own fork of this: `react-script-ts.` Thus, the main thing to do when migrating, is switching over this dependency:

```bash
$ npm uninstall react-scripts-ts
$ npm install react-scripts
```

Then, we have to make sure that the new scripts are the ones that are actually called when we run `npm start`, `npm test`, etc. Thus, in your `package.json`, replace:

```json
  "scripts": {
    "watch": "react-scripts-ts start",
    "build": "react-scripts-ts build",
    "test": "react-scripts-ts test --env=jsdom",
    "eject": "react-scripts-ts eject",
```

with

```json
  "scripts": {
    "watch": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
```

## Step 2: Activate TypeScript support

Although CRA now supports TypeScript, you do have to [explicitly enable it](https://facebook.github.io/create-react-app/docs/adding-typescript). This can be done by simply installing a few packages:

```bash
$ npm install --save typescript @types/node @types/react @types/react-dom @types/jest
```

## Step 3: Clean up the remnants of create-react-app-typescript

create-react-app-typescript did a few things differently from how Create React App proper does it, and therefore added a few files that now are no longer needed or are now named differently. Don't worry, though; we will recreate the relevant and properly named files in a moment.

The outdated files are `tsconfig.json`, `tsconfig.prod.json`, `tsconfig.test.json` and `images.d.ts`. To remove them with a single command:

```bash
$ rm tsconfig.json tsconfig.prod.json tsconfig.test.json images.d.ts
```

(Note that, apart from [a few options](https://github.com/facebook/create-react-app/blob/87e3d4fd1080d290f675d0461e3d3656752628ab/packages/react-scripts/scripts/utils/verifyTypeScriptSetup.js#L105-L129), you will still be able to customise `tsconfig.json` to your likings.)

## Step 4: Run it!

You should now be set! If you now run your app for the first time, Create React App will create relevant files, such as a new `tsconfig.json`, for you:

```bash
$ npm start
```

If everything went well, you should now have a running app. Not so bad, was it?

Depending on your setup, though, there might be a few additional problems you might run into.

## Troubleshooting

I will try to keep the following list up-to-date with problems that people run into, and how to solve them. Ran into any yourself that was not documented here? Let me know [on Twitter](https://twitter.com/VincentTunru) or <a href="mailto:blog@VincentTunru.com" title="Send me an email">by email</a>.

### Absolute imports

create-react-app-typescript allowed specifying your imports relative to your root directory. In other words, no matter which file you were editing, you could do

```javascript
// In src/components/Bar/Bar.tsx
import { Foo } from 'src/components/Foo/Foo.tsx';
```

This is useful because it allows you to move your files around as you please, but also makes it less transparent where your imports are coming from.

Create React App does not support this. To fix this, make your imports relative:

```javascript
// In src/components/Bar/Bar.tsx
import { Foo } from '../Foo/Foo.tsx';
```

### Importing CSS files from node_modules

In create-react-app-typescript, you could directly import CSS files that were located in `node_modules` from within a React component:

```javascript
// In Foo.tsx
import 'node_modules/bulma/css/bulma.min.css';
```

With Create React App, you can still import from `node_modules` but, like above, can not rely on absolute imports. However, you _can_ import directly from subfolders in `node_modules:`

```javascript
// In Foo.tsx
import 'bulma/css/bulma.min.css';
```

### Value not found, property does not exist on type, etc.

If you were using modern JavaScript API's in your code, you have to tell TypeScript to include the relevant type definitions. To do so, add the `lib` property to the `compilerOptions` in your `tsconfig.json`, and add the type definitions you use, e.g.:

```json
    "lib": ["esnext", "dom"]
```

Also make sure that, if you want to support older browsers like Internet Explorer 11, you [include the relevant polyfills](https://github.com/facebook/create-react-app/blob/master/packages/react-app-polyfill/README.md).

### Parsing error: Unexpected token

This can be the result of an ESLint configuration that does not incorporate Create React App's default configuration. If you have an `.eslintrc` file (possibly with an extension), add:

```json
  "extends": [
    "react-app",
    "react-app/jest"
  ]
```

(or add those two values to an existing `extends` property if present.)

If you don't have an `.eslintrc` file, add the following to your `package.json`:

```json
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
```

(or add this to an existing `eslintConfig` property if present.)

For more info, see https://github.com/facebook/create-react-app/issues/9791.

Thanks to Justus R for getting in touch to share this!

### Other type checking errors

Create React App enables strict mode for TypeScript. This can help you catch many errors, and I would suggest you to try to fix the errors you encounter. That said, create-react-app-typescript only enabled a subset of the strict type checking options, and moving to a stricter mode now might be too much of a hassle. To loosen these restrictions, you can try to manually disable the checks you are violating in the `compilerOptions` in your `tsconfig.json`, e.g.:

```json
    "alwaysStrict": false,
    "strictFunctionTypes": false,
    "strictPropertyInitialization": false,
```

### Allocation failed - JavaScript heap out of memory

If you use Yarn, adding or removing dependencies might start to fail. This is likely due to Yarn not being able to process the untold masses of dependencies. One factor that can strongly bloat your number of dependencies is if you are using [Storybook](https://storybook.js.org/) 3, because it includes other versions of Webpack, Babel, etc. than Create React App 2 is using. Luckily, Storybook _also_ just released a new version that should be compatible with the package versions used by Create React App, so following [the Storybook v4 upgrade instructions](https://medium.com/storybookjs/migrating-to-storybook-4-c65b19a03d2c) should solve this issue. Be sure to also read the paragraph below to make Storybook work.

### Storybook

Storybook uses its own Webpack configuration to load your stories. It uses `babel-loader` and, if you followed [the official docs on using TypeScript with Storybook](https://storybook.js.org/configurations/typescript-config/), `awesome-typescript-loader` to do so, which are not included with CRA. Thus, you will have to install those manually:

```bash
$ npm install babel-loader awesome-typescript-loader
```

Additionally, while Create React App uses Babel to parse JSX, Storybook expects TypeScript to do so. Thus, create a Storybook-specific TypeScript configuration in `.storybook/tsconfig.json` that extends the one you already have with that setting, as follows:

```json
{
  "extends": "../tsconfig",
  "compilerOptions": {
    "jsx": "react",
  },
}
```

Then, in `.storybook/webpack.config.js`, tell `awesome-typescript-loader` to use that configuration file:

```javascript
    loader: require.resolve('awesome-typescript-loader'),
    options: { configFileName: path.resolve(__dirname, './tsconfig.json') }
```

You should now be good to go!

## Thanks

The main driver behind adding TypeScript support to Create React App was [Bruno Lemos](https://twitter.com/brunolemos), who worked very hard on [his pull request](https://github.com/facebook/create-react-app/pull/4837). Of course, he could not have done that without the support of the Create React App team, and in particular [Joe Haddad](https://twitter.com/timer150), who spent a lot of time reviewing the pull request - and also reviewed this blog post. And of course, we should be grateful to [Will Monk](https://twitter.com/willmonk), who maintained ~~[(and is still maintaining)](https://github.com/wmonk/create-react-app-typescript/commit/ef987c15acad6468a35ddb0a24ba22add819207e)~~ his excellent fork of create-react-app that allowed us to use TypeScript when it was not officially supported yet.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


Migrating from create-react-app-typescript to mainline Create React App was surpisingly easy. Here's how to do it.

Migrating from create-react-app-typescript to Create React App

It can feel like [Babel](https://babeljs.io) and [TypeScript](https://www.typescriptlang.org/) have largely overlapping use cases: both allow you to use modern Javascript features, even before all relevant browsers support them. Thus, do you even need Babel when you use TypeScript? Or conversely: now that Babel [has added TypeScript support](https://babeljs.io/blog/2018/08/27/7.0.0#typescript-support-babel-preset-typescript), can you replace TypeScript with Babel? What's the difference? Why does a project like Create React App [combine the two](https://github.com/facebook/create-react-app/pull/4837)?

To learn the answers to these questions, it helps to consider TypeScript as doing three things:

1. It does type checking for your application.
2. It strips type annotations.
3. It transforms modern Javascript into versions understood by relevant browsers.

To illustrate these steps, let's consider how the following code is affected by each of those steps:

```typescript
const logNumber = (num: number) => console.log('The number is:', num);
```

The first thing TypeScript will do is to check whether you satisfy all the constraints set by the type annotations: type checking. After doing so, the code will look like this:

```typescript
const logNumber = (num: number) => console.log('The number is:', num);
```

That's right: it's exactly the same. Type checking does not actually alter your code; all it does is warn you if you break the assumptions encoded in its type annotations. In other words: if you were to call `logNumber('Not a number')` elsewhere in your code, TypeScript will warn you that you probably made a mistake — but it will not modify your code.

Or at least it won't before step 2: stripping type annotations.

```javascript
const logNumber = (num) => console.log('The number is:', num);
```

In this step, TypeScript removed everything that is TypeScript-specific (i.e. `: number`), preserving only that which is valid Javascript. In fact, an explicit design goal of TypeScript is [to produce "clean, idiomatic, recognizable JavaScript code"](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).

However, that arrow function [will still be problematic](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions#Browser_compatibility) for visitors using Internet Explorer. To remedy that, TypeScript can also transform this Javascript to older — but more widely supported — syntax:

```javascript
var logNumber = function (num) { return console.log('The number is:', num); };
```

Even plain Javascript projects often have the requirement that they should support older browsers. For the vast majority of those projects, Babel is the tool of choice to perform that transformation. And while you could always use Babel for that even in TypeScript projects, the increased complexity of setting up additional tooling often meant that that was not worth it.

With the release of [Babel's TypeScript plugin](https://babeljs.io/docs/en/babel-plugin-transform-typescript), however, Babel is now also able to perform step 2: the stripping of type annotations. That means that Babel can now handle every step that actually involves changing your code, with TypeScript running independently — and that's a game changer.

Why? First of all, it means that existing projects can now introduce TypeScript without having to introduce a new tool to their toolchain. With the addition of [a single Babel preset](https://babeljs.io/docs/en/babel-preset-typescript), developers can start using TypeScript without having to actually run the TypeScript compiler. They will still need to use e.g. an editor with TypeScript support to benefit from type checking, but doing so will not affect the way their code is built and run.

More important, perhaps, is the point of view of tooling authors. Projects like Create React App have many different users with many different needs. When part of their user base uses Babel to transform their code and another part uses TypeScript, they will have to test all those different configurations, making sure that e.g. [Sass](https://facebook.github.io/create-react-app/docs/adding-a-sass-stylesheet) works with both Babel and TypeScript, and to verify for every bug report whether the reporter is using Babel or TypeScript. Being able to use consistent tooling saves a lot of work and prevents a lot of bugs.

In other words, tooling authors can now add support for TypeScript without negatively affecting the part of their user base that does not use TypeScript, while limiting the divergence between those who do and those who don't.

Of course, this also benefits developers using those tools. Adding a layer of type checking on top of the tooling used by the rest of the ecosystem, rather than replacing parts of that tooling with TypeScript, allows you to build on a more widely tested foundation and to leverage existing support channels and documentation. With that, TypeScript and Babel appear to be a winning combination.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


Do you need Babel when you use TypeScript, or vice versa? Does it make sense to combine the two?

Why combine Babel and TypeScript?

Working at a small, young and frugal non-profit, I do not have the luxury of specialised testers giving new features a run-through before they go live. Nevertheless, because our code runs on the websites of other organisations, we have to make absolutely sure that it will not break. At the same time we want to be able to iterate quickly as we adapt to a rapidly changing environment. We manage to balance these two requirements by a variety of measures. Combined, they result in an excellent developer experience, in which I can regularly and confidently deploy code to production.

In this post, I will discuss our approach, starting with the relatively standard elements, building up to the more exciting cutting-edge techniques. All of this uses freely available open source projects.

## The basics: a build pipeline

Like many projects, we have set up a build pipeline: a set of tasks that get run every time code gets pushed to the central repository. This pipeline runs a few basic checks before and after code gets merged into `master`: does the code build successfully, do all unit tests succeed, and what code is covered by them? If a pipeline fails, I receive an email notification. If there's a related open merge request, it will display a warning before merging.

This pipeline already removes a lot of potential for human error. For example, if I forget to run unit tests locally and I break some, that code will not make it into the main codebase without me noticing. Likewise, I could forget to check in parts of my code. Even though tests would still succeed for me locally, the pipeline would fail, and I will immediately be notified. This is vastly preferable over distributing incomplete and broken code to other developers or, worse, users.

Artifacts like e.g. the code coverage report produced during the pipelines are also visible to all team members.

![Screenshot of a code coverage report, displaying a few lines of code that have been run during tests.](/img/fearless-deployments/coverage-report.png)

Our pipelines are powered by [GitLab CI/CD](https://about.gitlab.com/product/continuous-integration/).

## Review apps

Review Apps are the backbone of everything that is to come. The basic concept of a review app is spinning up an entirely new and disposable production-like environment for every branch, with that branch's code deployed to it. My basic workflow is to create a new branch whenever I start solving an Issue, straight from the GitLab interface.

![Screenshot of the GitLab interface, creating a branch called `98-ci-example`](/img/fearless-deployments/branch-from-issue.png)

These branches are automatically named using the format `<issue number>-<issue description>`, e.g. `98-ci-example`. Upon creating that branch, a new pipeline automatically runs, deploying the code in that branch to https://98-ci-example-review.plaudit.pub.

![Screenshot of the Plaudit website deployed to https://98-ci-example-review.plaudit.pub, next to the Issue it was created for.](/img/fearless-deployments/review-app.png)

The advantages of review apps are numerous. It allows me to easily verify whether and how my code works in a clean environment. It tells me that deployments still work as expected, and hence will likely do so when I deploy my code to production as well. And finally, it enables a variety of automated sanity checks on the live application, such as checking for performance regressions or potential security issues.

The primary tool used to provision these new environments is [TerraForm](https://www.terraform.io). It allows you to define the infrastructure you need using a configuration file, and to pass the relevant branch name as a parameter.

## End-to-end tests

Of course, I _could_ visit the deployed review app to check whether everything's OK... But why go through the effort when that, too, can be automated? After a review app gets deployed, the build pipeline automatically fires up Chrome and Firefox. They will then visit the newly deployed app, try to run through a few basic scenario's, and then report on whether they were able to do so successfully.

![Screencast showing the progress of a single end-to-end test running in Firefox.](/img/fearless-deployments/end-to-end.webm)

These end-to-end tests buy me two things. First, they can warn me when a deployment was unsuccessful. Even a simple test that literally just visits the page and checks whether a single DOM element is present is enough to tell you whether the new infrastructure was successfully set up, the code was deployed successfully, and the server is running as expected. Second, they run some basic tests trying to navigate the app by keyboard - an important accessibility concern that is easy to mess up.

The end-to-end tests use [Selenium](https://docs.seleniumhq.org) for browser automation, and [WebdriverIO](https://webdriver.io) to run the checks.

## Storybook

Our primary product is a widget that can be in many different states, and adapts its looks to the space it's allotted. It is therefore useful to be able to see what the widget looks like in all those different variations, without having to reproduce all the steps required to get the widget into those states. To facilitate this, with every review app we also deploy a storybook.

![Screenshot of a storybook showing our "endorsement" widget, with links on the left-hand side to switch between states like "No endorsements", "One endorsement" or "More than three endorsements".](/img/fearless-deployments/storybook.png)

Using the storybook, it's just a single click in order to inspect the [various states](https://medium.com/swlh/the-nine-states-of-design-5bfe9b3d6d85) the app can be in: no data, some data, too much data, logged in, logged out, etc. This makes it very easy to quickly check the impact of CSS changes on the widget in all its different faces.

The storybook is made possible by the aptly-named project [Storybook](https://storybook.js.org).

## Visual regression tests

Still, having to manually inspect the widget in all its various states on every change is rather time-consuming. Luckily this, too, can be automated. Whenever a pipeline is run, the storybook is opened in a browser, and screenshots of the widget in every state are compared to checked-in reference screenshots. When the two diverge, the pipeline fails and a report is generated highlighting the differences between the deployed widget and the reference image.

![Screenshot of a report on a visual regression test, displaying one failed test case showing three images: the reference image, the taken screenshot, and the two overlapped with their differences highlighted in pink.](/img/fearless-deployments/visual-regression-test.png)

This will make sure that I receive a notification whenever I alter the layout of the widget, which is very helpful when those changes were unintentional. For example, I recently found out that Chrome does not support `<button>` elements acting as [flex containers](https://developer.mozilla.org/en-US/docs/Glossary/Flex_Container), due to which a supposedly minor accessibility change ended up messing up the layout in a specific state.

The regression tests are executed by [Gemini](https://gemini-testing.github.io).

## Wrapping up

Combined, all these tools provide me with a lot of reassurance whenever I am ready to push my code to production. They have prevented repeated occurrences of actual problems I have run to in the past, and seeing a row of green checkmarks before merging into `master` provides a lot of reassurance.

![Screenshot of a merge request report, showing successful security, performance, code quality and regular tests.](/img/fearless-deployments/code-checks.png)

These tools were added incrementally over time, in response to actual encountered problems. I hope that showing what's possible using off-the-shelf open source tools will encourage you to investigate what could be possible and useful in your own projects as well. The exact setup will vary per project, but you're welcome to look at [ours](https://gitlab.com/Flockademic/plaudit/blob/master/.gitlab-ci.yml) as a starting point!

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


I describe a number of measures that help me to regularly deploy to production without fear of my code breaking.

Fearless deployments


In my time, I've done a number of side projects — some [serious](https://agripongit.vincenttunru.com), some [decidedly less so](https://makeapoint.vincenttunru.com). My latest side project is quite definitely in the latter category: trying to win a game show on national television.

## Lingo

The show in question is [Lingo](https://en.wikipedia.org/wiki/Lingo_(Dutch_game_show)), a show that ran in the Netherlands for 25 years and, after a 5-year hiatus, returned on air this year. Roughly speaking, it can be described as [Mastermind](https://en.wikipedia.org/wiki/Mastermind_(board_game)) with words.

The goal is to guess a five- or six-letter word in at most five guesses. The first letter is given, and after every guess players are told which letters their guess shares with the actual word, and which of those are also in the correct position. An example should clear things up.

![](/img/hacking-a-gameshow/aspect.png)

Let's say it's my turn. The word to find is _aspect_ — but of course, I don't know that yet. All I know is that the word is six characters long, and starts with the letter _a_. My first guess is 'actors' which, although not the word we're looking for, does share the letters 'c', 't' and 's' with the one we _are_ looking for, albeit in different positions.

Still clueless about the actual word, my next guess is 'assume'. Now, not only is the letter 'e' part of the word we're looking for, but the first 's' is actually in the same place! Given that I now know that the first two letters are an 'a' and an 's', and that the rest of the word contains a 'c', a 't' and an 'e', I can make a reasonably informed guess that the word we're looking for is, in fact, _aspect_.

Two teams take turns guessing a word. Roughly, the team that guesses most words correctly wins.

## Our strategy

One way to win at Lingo is to have a large vocabulary and a keen eye. I teamed up with my brother, and although we both speak Dutch just fine, we are certainly not good enough to win this game — we barely even made it through the qualifiers.

So we started working on a strategy to increase our odds of winning. Of course, we're not the first ones to try to do so: a commonly adopted strategy is to memorise a list of words that cover most of the vowels. Using those words as the first guesses increases the likelihood of letters overlapping with the word you're looking for. However, we felt there was still room for improvement to this strategy.

By focusing on vowels, you are pretty much guaranteed to find at least one of the target word's letters, and maybe one or two more if you're lucky. But if we were to focus not just on the vowels, but on the most common letters for every possible first letter, we might be able to push that number up quite a bit!

So I set to work. The first step was to find a list of all the possible words in the Dutch language. Luckily, Wikipedia's fantastic sister project [Wiktionary](https://www.wiktionary.org) has carefully [documented](https://en.wiktionary.org/wiki/Wiktionary:Frequency_lists) their efforts to determine which words they should focus on. That led me to the fantastic work by [Hermit Dave](https://invokeit.wordpress.com), who parsed a large number of subtitles to compile [Frequency Word Lists](https://github.com/hermitdave/FrequencyWords/) for many languages, including Dutch.

Word list in hand, I wrote a script to count the most frequently occurring letters for every starting letter, for both five- and six-letter words. For example, it enumerated all six-letter words that start with an `s`, then tallied how many of them contained an 'a', how many of them contained a 'b', etc.

![](/img/hacking-a-gameshow/tally.svg)

Then, for each of those words, it considered how often the letters of those words were used in the entire list, and gave me one of the words that cover most occurrences.

![](/img/hacking-a-gameshow/topword.svg)

It then went on to select the word that contained the most frequently occurring of the remaining letters _not_ covered by the selected word.

![](/img/hacking-a-gameshow/secondword.svg)

That was repeated once more to end up with a list of three words that show significant overlap with most six-letter words starting with an 's'.

The entire process was repeated for every letter in the alphabet, over both five- and six-letter words. By memorising all of them, my brother and I could spend our first three guesses covering as many relevant letters as possible, and then have two more guesses remaining to find the correct word.

(Fun fact: my brother [is a comedian](https://www.andriestunru.nl), and in one part of his latest show he asks members of the audience to prompt him with letters, to which he'll respond by rattling off the words we memorised. He's still got it!)

## Practice makes perfect

While it wasn't feasible for us to significantly expand our vocabulary in preparation for the show, we could certainly improve our ability to find the right words given a set of letters. Thus, I wrote [a small practice application](https://lingo.vincenttunru.com) ([source code](https://gitlab.com/vincenttunru/lingo/)) that would serve us words from the word lists, take our guesses, and then rate them.

![](/img/hacking-a-gameshow/app.webm)

This was a great help not only in memorising words, but also to help us detect and internalise patterns. For example, we learned that often, if only few letters were covered by our initial three words, the gaps would be repeat occurrences of the letters we _did_ already find.

Additionally, since the words were also selected from the list, it gave a more realistic picture of the words we'd encounter in practice: we'd be more likely to encounter words starting with an 's' that those that start with a 'z'.

## So, how did it go?

Pretty well! Although the game still involves quite a bit of luck, we were certainly aided by our far too extensive preparations in achieving a winning streak lasting a week. But of course, given the incredible geekiness of it all, the most important thing is that [we had a lot of fun doing it](https://www.sbs6.nl/programmas/lingo/videos/Vk9EpXSlwas/lingo/).

![](/img/hacking-a-gameshow/on-the-show.png)

(And for the Dutch readers: yes, the [word that went viral](https://www.dumpert.nl/item/7803325_e71d8b7e) was actually one of the best three.)

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


My latest side project involved writing software that helped me win a game show on national television.

How I spent way too much effort to win a game show on national television


Ah, Semantic Versioning. The concept sounds simple enough, but it's been the source of untold lost hours of confusion and disagreements. I'd like to offer up a small change in perspective that I hope will help settle such issues once and for all.

The root of the problem lies in the fact that we generally live under the illusion that [words have clear and unambiguous inherent meaning](https://en.wikipedia.org/wiki/Intersubjectivity#Philosophy). From there, we draw the mistaken [conclusion](https://twitter.com/SeaRyanC/status/1220415231396106241) that we can unilaterally assign meaning to version numbers as well.

However, _meaning_ is a common understanding between two or more participants in a conversation. SemVer, therefore, cannot be understood without considering the parties in the conversation. Specifically, a semantic version number is a message from a package's author to its consumer. We can resolve many questions surrounding semantic versioning by considering the intention of the speaker (the package author), and the conclusions they want the listener to draw.

![](/img/semver-explained/SemVer-conversation.png)

So given a version number `<major>.<minor>.<patch>`, let's consider what conclusions a package's author wants its consumer to draw when they increment:

- …the **patch** version number: that the author expects the consumer to be able to blindly upgrade from the previous version. If they were waiting for a specific bug to be fixed, they may want to check the release notes to see if they can remove any workarounds they have put in place.
- …the **minor** version number: that the author expects the consumer to be able to blindly upgrade, but would recommend checking the release notes. It might contain relevant new features, or introduce the deprecation of existing functionality and its replacement, the migration to which the consumer will probably want to start planning.
- …the **major** version number: that the author expects that this new release might break something for the consumer, and therefore suggests reviewing the release notes before attempting the upgrade. Ideally, most of the required changes involve functionality that was deprecated in an earlier release, and have therefore already been dealt with on the consumer's own schedule. Unfortunately, this is not always possible.

The assumption with all of the above expectations is that the consumer has stuck to the publicly documented API. It is hard enough to predice the impact of changes as it is; it would be nigh impossible if unforeseen use cases would also need to be taken into account.

With this new perspective in hand, let us finish up this post by considering a couple of questions that commonly arise regarding SemVer, both from the perspective of a package's author as well as from its consumer. Get in touch if you have any to add!

### Package author dilemma's

#### "Is it a breaking change if I change around my UI?"

Is there someone who is going to consciously make decisions based on your version number? In other words, is your version number actually a conversation, or is there no listener? For many user-facing projects, there actually is no person making decisions based on your version number, in which case SemVer doesn't actually add value — so why bother?

#### "Is this bugfix a breaking change? It changes my package's behaviour."

Is the buggy behaviour part of your publicly documented API? If not, your consumers should not be relying on it — if they find a discrepancy between the documentation and what actually happens, they should file an issue.

[![](/img/semver-explained/xkcd-1172.png)](https://xkcd.com/1172/)

#### "But lots of my users rely on this undocumented behaviour!"

Well, if you *know* they do, then by all means, increment the major version! You're trying to help your users deal with your new version, and while a major version increment is more work to evaluate, unexpected breakage is even worse.

If you think the risk of breaking changes in bug fixes is particularly large, you could even consider [forgoing patch version increments altogether](https://staltz.com/i-wont-use-semver-patch-versions-anymore.html).

#### "I've added a major new feature. Do I increment the major version number?"

While forcing your users to look at your release notes is a good way to advertise new features, it greatly increases the burden of the upgrade. So unless you have particularly engaged users, consider whether they really are best served with a major version increment.

#### "My API is super-generic, is it really a breaking change if I break just _some_ of the use cases?"

As with internal API's, adding [too much abstraction](https://twitter.com/VincentTunru/status/1265238324236648449) to your external API makes it harder to change. If you want your users to be able to trust your version numbers, then you should increment the major version number if you expect it to break for them.

#### "So I can just introduce as many breaking changes as I want, as long as I increment the major version number?"

SemVer makes it easier for your users to judge the amount of work required to upgrade, but it doesn't decrease that amount of work. Avoiding breaking changes as much as possible, providing migration paths if doable, will still be greatly appreciated by your users.

#### "What if I don't want to do SemVer?"

Then don't do it :) That said, if you're in an ecosystem in which SemVer is common, it would be courteous to state that upfront to avoid people making incorrect assumptions.

### Package consumer dilemma's

#### "Who do I sue if a minor or patch upgrade broke for me?"

Notice how often I used the word "expect", before? There is no way for a package author to know your codebase, so these version numbers communicate their best human judgment — which could be wrong. Caveat emptor; proper QA infrastructure will always be important.

#### "There is undocumented functionality that would really be useful to me. Can I use it?"

Sure, but then all bets are off: even patch increments could introduce unforeseen breakage in your code, so you would do well to inspect the changelog even for non-major upgrades. You might also want to configure your package manager not to depend on a version range.

#### "Can I expect a project to be stable once it reaches version 1.0.0?"

SemVer only says that the above increments will be observed from v1 onwards — not that no more breaking changes will be released at all. In general, I'd expect a young project to still be figuring out its API, whereas an older project is more likely to be stable.

For example, [React.js](https://reactjs.org) iterated through its first major versions relatively quickly, but has been on version 16 for over two years at the time of writing.

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/), with the exception of the comic by Randall Munroe, licensed under a [Creative Commons Attribution-NonCommercial 2.5 License](http://creativecommons.org/licenses/by-nc/2.5/)._


Semantic versioning explained with examples

The concept of Semantic Versioning sounds simple enough, but it's been the source of untold lost hours of confusion and disagreements. A small change in perspective can help settle such issues once and for all.

Let's talk about SemVer


It appears that [Tailwind](https://tailwindcss.com/) is somewhat contentious: it's either the best thing since sliced bread or [literally provides no value](https://dev.to/brianboyko/tailwindcss-adds-complexity-does-nothing-3hpn#it-literally-provides-no-value-and-tons-of-problems). While such extremes might make for interesting reading, the proper way to evaluate technologies is to attempt to understand the problems they solve, and then determine whether those are problems you actually have.

So let me try to help with that. In a nutshell, Tailwind is worth considering if you:

- don't have an eye for design,
- use a component-based architecture, and
- prefer simple build tooling.

Let me elaborate.

## Constraints set you free

Let me start with what I think is both Tailwind's main benefit and the one that's most often overlooked: its constraints.

On first sight, it looks like Tailwind provides just a bunch of CSS classes that each represent a single style declaration:

```html
<article class="bg-blue-200 p-5">
  <h1 class="text-3xl">Corporate Ipsum</h1>
  <p class="py-2">
    Leverage agile frameworks to provide a robust synopsis for high level overviews.
    Iterative approaches to corporate strategy foster collaborative thinking to further the overall value proposition.
  </p>
</article>
```

Technically, an equivalent result could be achieved with inline styles:

```html
<article style="background-color: #bfdbfe; padding: 1.25rem;">
  <h1 style="font-size: 1.875rem; line-height 2.25rem;">Corporate Ipsum</h1>
  <p class="padding-top: 0.5rem; padding-bottom: 0.5rem;">
    Leverage agile frameworks to provide a robust synopsis for high level overviews.
    Iterative approaches to corporate strategy foster collaborative thinking to further the overall value proposition.
  </p>
</article>
```

That's about the same amount of work!

However, take note of what you _can't_ do with Tailwind: while you can apply vertical padding of `0.25rem` (`py-1`) or `0.5rem` (`py-2`), you _cannot_ set it to `0.3rem`! Likewise, while you can set the background colour to `#dbeafe` or to `#bfdbfe`, you cannot set it to `#c8d2fe`.

Tailwind's constraints are minimal enough that no two websites created using it look the same, but strong enough to practically enforce consistency throughout. Regardless of whether you use a `p-5` here and a `p-2` there, all possible values have been [explicitly chosen to complement each other](https://styled-system.com/guides/why-powers-of-two/) without anything looking "off". Likewise, Tailwind includes a default colour palette allowing you to use different shades of the same colour, both complementing each other and in most cases providing sufficient contrast to ensure everything is visible even in a sunny environment or for users with visual impairments.

A good designer will have an eye for such consistency. However, they are not always around, and even when they are, designs are rarely exhaustive. A constraint-based design system like Tailwind will assist engineers in making the right design choices when they need to do so.

Other tools that can help you achieve this goal are: [Styled System](https://styled-system.com/), or a set of custom [Sass](https://sass-lang.com/) or [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) variables (e.g. [Universal Tokens](https://tw-tokens.netlify.app/)).

## The right abstraction

One of the reasons Tailwind felt "wrong" to me when I first saw it, was because it went counter to how I've always been taught I'm _supposed_ to do things.

So let's consider how we were supposed to do things, why we were supposed to do them that way, and whether those reasons still apply.

The core idea behind CSS, as illustrated by the venerable [CSS Zen Garden](http://www.csszengarden.com/), was that you use semantic HTML to describe what the content of your page _is_ (e.g. a heading, emphasised text, a link, etc.), and CSS to determine what it should _look like_ (e.g. larger, in italics, underlined, etc.).

![](/img/why-tailwind/css.png)

In other words, the idea is to take your DOM structure as a given, and use CSS as the source of truth for what the website should look like: for example, perhaps links inside a profile card should be bold, whereas links inside the main content should not.

Like all abstractions, this comes at a cost. The most important of which is the almost inevitable case of append-only CSS: since it's hard to tell whether a particular rule still matches anything on the site, it's practically impossible to delete unused styles.

It also turns out that separation of concerns isn't as clear-cut as might have been hoped: it is rare that achieving a desired layout does not involve adjustments to both CSS _and_ HTML.

This is an important reason why Single-Page Application frameworks like [React](https://reactjs.org/), [Vue](https://vuejs.org/), [Svelte](https://svelte.dev/) and [Angular](https://angular.io/) encourage architectures in which applications compose together components consisting of particular combinations of different elements. These are then accompanied by CSS that style those components' particular combinations of elements in the desired way.

![](/img/why-tailwind/component.png)

In other words: in practice, changing what a component looks like often involves changes to both that component's HTML and CSS. And if that's the case, is that split still worth it? Is this particular abstraction still carrying its weight?

Tailwind's answer is no. Why add component-specific classes, if those components already take care of making our styles reusable?

Tailwind puts the component in charge of styling, instead of a global stylesheet tailored to a particular combination of DOM elements. This gives you the ability to reuse styling across your app, the confidence to remove unused code, and a single place to change when updating styles.

![](/img/why-tailwind/tailwind.png)

Other tools that help defining component-specific styles are one of the [various](https://www.smashingmagazine.com/2011/12/an-introduction-to-object-oriented-css-oocss/) [naming](http://smacss.com/) [conventions](http://getbem.com), or one of the various CSS-in-JS tools like [CSS modules](https://github.com/css-modules/css-modules), [JSS](https://cssinjs.org/), [styled-components](https://styled-components.com/) or [Emotion](https://emotion.sh/).

## Simple tooling

With the exception of the use of naming conventions, most attempts to make CSS more predictable in a component-based architecture involve relatively complex tooling. This often requires multiple layers of your stack to be aware of this tooling, makes dependency upgrades more painful, can introduce delays to your development flow, and in the worst case [impacts the performance for your users](https://pustelto.com/blog/css-vs-css-in-js-perf/).

With Tailwind just relying on CSS classes, it is relatively simple and independent of the rest of your tooling: all you really need is a CSS file that includes the definitions of the Tailwind classes you use.

Granted, Tailwind defines so many classes that you can't feasibly just dump all of them into a stylesheet and call it a day: the resulting stylesheet would take far too long to download. Instead, it needs to generate a stylesheet defining just the classes you use. The good news is: generating such a stylesheet can be done using relatively "dumb" tooling: Tailwind just considers all its class names, and checks which of those literally occur in your code base. No need for something as complex and brittle like parsing your HTML, JSX, or whatever language you're writing in.

Sure, the flip side is that if you also happen to have a Markdown file that happens to mention `md:bg-blue-100`, that class will also be included even though it's not _actually_ used anywhere. But if that happens to a few classes, the impact is negligible, and certainly worth the tooling simplicity.

## So when is Tailwind right for you?

If you can use some help to make your designs look consistent, use a component-oriented architecture, and would like to avoid complex tooling, I can warmly recommend you to give Tailwind a try sometime.

And if not... Tailwind might just not solve a problem you have, and that's fine too!

(This article was adapted from a [Twitter thread](https://twitter.com/VincentTunru/status/1330103979762651138).)

[![License](//i.creativecommons.org/l/by/4.0/80x15.png)](//creativecommons.org/licenses/by/4.0/)

_This work by [Vincent Tunru](https://vincenttunru.com/) is licensed under a [Creative Commons Attribution 4.0 International License](//creativecommons.org/licenses/by/4.0/)._


(When) is Tailwind right for you?


When React first burst onto the scene, its primary innovation was the Virtual DOM: instead of having to manually make sure the DOM is in sync with the actual application state, you'd just recreate a representation of the full DOM on every state change, and React would then update the actual DOM with exactly the changes needed to make it match. React components were simply a function of the application state, and the main benefit of that, as was the slogan at the time, is that it makes them _easy to reason about_. We were now able to create highly interactive client-side applications without introducing countless subtle bugs that were hard to catch.

Although that enabled way richer client-side applications than before, all that logic could only be executed once the code was downloaded and parsed by the user's browser, with nothing bug a blank page for the user to stare at. So we started doing Static Site Generation: do the first render of the virtual DOM at build time, and use that to send the user some HTML that can be shown while waiting for the client-side code to run. Of course, since that first render is done on the server side, you can't use client-side APIs in there, so make sure to keep in mind what environment the code you're writing might be running in. For example, you could set a state variable as a side-effect, and then wrap your code in a check for that variable.

One downside is that SSG happens at build-time, and thus only works for HTML that looks the same for every user. So we came up with tricks to customise the initial payload at runtime: Server-Side Rendering. Often implemented as separate APIs which only run on the server-side, and thus can access server-side APIs and secrets to fetch the relevant data for the user, and then pass those as props to your components. Of course, if that data is updated in the lifecycle of the client-side application, then that will have to make sure that the updated data is shown instead of the initial data passed as props.

With SSR we could now always send useful HTML while the user was waiting for the client-side code to have run, but we can't start sending that until we've collected _all_ the data a page needs, no matter how unimportant. Besides, it was bolted on top of React through proprietary APIs specifc to the different frameworks that implemented it. So we got server components in React itself, which can be rendered completely on the server, sent as soon as they're ready, and don't have to (virtually) be rendered again on the client-side, thus no longer delaying the client-side interactivity.

These server components look similar to traditional, now-known-as client components, can access async and server-side APIs, but they cannot access client-side APIs, nor state and effects. Client components will usually _also_ render on the server, so also make sure not to access client-side APIs in their first render. Also, you can have individual functions inside client components call server-side APIs if they're submit event handlers for forms, or wrapped in a "transition", and have `"use server"` at the top of the function body. Components are server components by default, but become client components if they have `"use client"` at the top. Well, or if one of their parent components has that, so make sure you to check where your component gets used before accessing server- or client-side APIs, or avoid both altogether.

## Is React too complex?

Well… In theory, the changes have been strictly additive: it is still perfectly possible to build an app that is fully rendered on the client side, and the view is mostly a function of state. What _has_ changed, is our demands: we want the first-load performance of traditional, fully server-rendered websites where possible, combined with the reliable highly-interactive client-side experiences where needed. It's possible that exercising such granular control just comes with inherent complexity, and React is the best we can do in terms of managing that.

But maybe not?


React's main benefit used to be that it was easy to reason about. Is it still though?

I've written about: