Harden up Node.js with Flow: Part 1

Feeling inadequate that you are not using a statically typed language; like the hotness of Go? Now you to can feel better with Flow.

FLOW IS A STATIC TYPE CHECKER FOR JAVASCRIPT.

— Facebook Open Source Team

Prerequisites

You will want a recent version of Node.js (≥ 8.9.3); I was using 8.9.3.

While not critical, I find it useful to use nvm to manage the versions of node that I am developing on.

Before

We start with a simple Node.js project (complete example available). In this case, it is the Node.js hello world example with linting enabled (because coding without linting is painful). Linting is provided by the eslint tool and the eslint-config-airbnb-base configuration (see their install instructions).

With this setup; the eslint configuration is:

.eslintrc.js

module.exports = {
  extends: 'airbnb-base',
  plugins: [
    'import',
  ],
  env: {
    node: true,
  },
};

the command-line method of linting your code is:

./node_modules/.bin/eslint index.js

Many editors / IDEs, at the same time, have eslint integration features; in my case I use the linter-eslint plugin for the Atom editor.

After

Our first example, simply integrates Flow into our earlier simple Node.js project (complete example available).

We start by following the instructions on installing Flow. A couple of observations:

• For those who have been writing front end JavaScript lately, the idea of transpiling JavaScript is neither novel or new.
• Because the recent versions of npm have many of the benefits that drove us to use the Yarn package manger, we will use npm here.
• Because Babel is the defacto-standard tool for transpiling JavaScript on the front end, we will stick with using it for Node.js.
• Because we are focusing on build reliability, we will be additionally using the npm save-exact option; saves the exact version in package.json.
• Because we don’t want to commit the transpiled code to your GIT repository, we add **/lib to the .gitignore file.

Before we can use Flow, we need to setup eslint to support Flow using eslint-plugin-flowtype (follow their installation instructions). Because we were already using eslint, our specific configuration is as follows:

.eslint.js

module.exports = {
  parser: 'babel-eslint',
  extends: [
    'airbnb-base',
    'plugin:flowtype/recommended',
  ],
  plugins: [
    'import',
    'flowtype',
  ],
  env: {
    node: true,
  },
};

Now we can follow the instructions for using Flow; deliberately introduces a error that Flow will detect. In our case, we can introduce the problem code into index.js.

src/index.js

// @flow
/* eslint-disable no-console */
const http = require('http');
function foo(x: ?number): string {
  if (x) {
    return x; // BROKEN
    // return x.toString(); // FIXED
  }
  return 'default string';
}
const hostname = '127.0.0.1';
const port = 3000;
const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end(foo(2));
});
server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`);
});

A couple of observations:

• As configured, the linter does not identify any errors in the project; it is valid JavaScript + Flow code.
• Running the built version with node lib/index.js will generate a runtime exception when the endpoint is hit, throw new TypeError(‘First argument must be a string or Buffer’);
• Flow does identify the error by running npn run flow in the project (below).

Error: src/index.js:7
  7:     return x;
                ^ number. This type is incompatible with the expected return type of
  5: function foo(x: ?number): string {
                               ^^^^^^ string

This simple example gives us a glimpse of the advantage of using Flow; it can catch subtle errors that linting cannot before they appear as runtime errors (and thus possibly in front of your customers).

To fix the code, simply comment out the code labeled BROKEN and uncomment the code labeled FIXED.

Import

Because I find myself frequently switching between writing front-end and back-end code, I find it helpful to able to write everything in ES6 without thinking about what build environment I am in. Specifically, Node.js (8.9.3) does not support the ES6 import syntax.

Now that we are using Babel (for Flow), we can now use another Babel preset, babel-preset-env, to enable us to write everything in ES6 (complete example available).

npm install babel-preset-env --save-dev --save-exact

.babelrc

{
  "presets": [
    ["env", {
      "targets": {
        "node": "8.9"
      }
    }],
    "flow"
  ]
}

With this in place we can use imports now.

src/index.js

// @flow
/* eslint-disable no-console */
import http from 'http';
function foo(x: ?number): string {
...

Next Steps

We continue our exploration in Harden up Node.js with Flow: Part 2.