Make Your JavaScript Code Robust With Flow

JavaScript was always a significant programming language, being the only language that runs reliably in the browser. Recent trends in front-end development as well as Node.js based back-end development have pushed the scale and complexity of JavaScript applications. 

Large applications developed by large teams can benefit from static type checking, which vanilla JavaScript lacks. Flow was developed by Facebook to address this issue. It is a static type checker that integrates into your development process, catches a lot of problems early, and helps you move fast.

What Is Flow?

Flow is a tool that checks your annotated JavaScript code and detects various issues that without it would be discovered only at runtime (or worse, not discovered and corrupt your data). Here is a quick example.

Flow vs. TypeScript

Before diving into the nitty-gritty details of Flow, it's worthwhile to
compare it against other alternatives, and in particular TypeScript.
TypeScript is a strict superset of JavaScript developed by Microsoft.
Any JavaScript program is also a TypeScript program. 

adds optional type annotations and overall serves the same purpose as
Flow. However, there are some important differences. TypeScript is a
separate programming language that compiles to JavaScript, whereas Flow
annotations must be removed to get back to valid JavaScript. 

TypeScript has great tool and IDE support. Flow is catching up (e.g. JetBrains WebStorm has native Flow integration).

most important philosophical difference is that Flow puts an emphasis
on soundness. TypeScript 1.0 didn't catch null errors; TypeScript 2.0
with strict null checks measured up to Flow in this regard. But in
other aspects such as generic containers or typing, TypeScript is more
permissive and lets various categories of errors through (only structural
typing is checked, not nominal typing).

TypeScript as its own
language adds concepts and language features such as classes,
interfaces, visibility indicators (public, private, readonly), and
decorators. Those features make it easier to understand and use for
people coming from mainstream object-oriented languages like C++, Java, and C#.


Since Flow annotations are not
standard JavaScript, they need to be removed before deploying your
application. Here is how to install flow and flow-remove-types via yarn: yarn add --dev flow-bin flow-remove-types

You can add a couple of scripts to your package.json file to automate the process:

You should run the prepublish script before publishing your code to the npm registry.

For other installation options (e.g. using npm or babel), check out the Flow installation guide.

To finish the installation, type: yarn run flow init

This will create the required .flowconfig file.

Type System

Flow has two important goals: precision and speed. Its type system was designed to support these goals.


Precision is achieved by analyzing how the code interacts with types, either annotated or inferred. Any mismatch raises a type error. Annotated types support nominal typing, which means that two different types with the same attributes are distinguished from each other and can't be substituted. The type of a variable is defined as the set of runtime values the variable may receive. 


Flow is fast due to a combination of modularity and distributed processing. Files are analyzed in parallel, and the results are merged later via efficient shared memory to accomplish full-program type checking.

Supported Types

Flow supports many types. In addition to primitive types, it also supports the following:

  • Object
  • Array
  • Any
  • Maybe
  • Variable
  • Tuple
  • Class
  • Interface
  • Generic

Type Annotations

Flow allows you to declare types as well as restrict variables and parameters to selected values:

If you exceed the valid range, you'll get an error:

You can also define complex types, including subtyping. In the following code example, the Warrior type is a subtype of Person. This means it is OK to return a Warrior as a Person from the fight() function. However, returning null is forbidden.

To fix it, let's return the younger warrior if both warriors have the same strength:

Flow allows even more precise control via class extension, invariance, co-variance, and contra-variance. Check out the Flow documentation on variance.


Flow uses the .flowconfig configuration file in the root directory of your projects. This file contains several sections that let you configure what files Flow should check and the many aspects of its operation. 


The [include] section controls what directories and files should be checked. The root directory is always included by default. The paths in the [include] sections are relative. A single star is a wild-card for any filename, extension, or directory name. Two stars are a wild-card for any depth of directory. Here is a sample [include] section:


The [ignore] section is the complement to [include]. Files and directories you specify here will not be checked by flow. Strangely, it uses a different syntax (OCaml regular expressions) and requires absolute paths. Changing this is on the roadmap of the Flow team.

Until then, remember that the include section is processed first, followed by the ignore section. If you include and ignore the same directory and/or file, it will be ignored. To address the absolute path issue, it is common to prefix every line with .*. If you want to ignore directories or files under the root, you can use the <PROJECT_ROOT> placeholder instead of .*. Here is a sample [ignore] section:


Any non-trivial JavaScript application uses lots of third-party libraries. Flow can check how your application is using these libraries if you provide special libdef files that contain type information about these libraries. 

Flow automatically scans the "flow-typed" sub-directory of your project for libdef files, but you may also provide the path of libdef files in the [libs] section. This is useful if you maintain a central repository of libdef files used by multiple projects.

Importing existing type definitions and creating your own if the target library doesn't provide its own type definitions is pretty simple. See:


Flow has several lint rules you can control and determine how to treat them. You can configure the rules from the command line, in code comments, or in the [lints] section of your config file. I'll discuss linting in the next section, but here is how to configure it using the [lints] section:


The [options] section is where you get to tell Flow how to behave in a variety of cases that don't deserve their own section, so they are all grouped together.

There are too many options to list them all here. Some of the more interesting ones are:

  • all: set to true to check all files, not just those with @flow
  • emoji: set to true to add emojis to status messages
  • module.use_strict: set to true if you use a transpiler that adds "use strict;"
  • suppress_comment: a regex that defines a comment to suppress any flow errors on the following line (useful for in-progress code)

Check out all the options in the Flow guide to configuring options.


Flow and its configuration file format evolve. The [version] section lets you specify which version of Flow the config file is designed for to avoid confusing errors.

If the version of Flow doesn't match the configured version, Flow will display an error message.

Here are a few ways to specify the supported versions:

The caret version keeps the first non-zero component of the version fixed. So ^1.2.3 expands to the range >=1.2.3 < 2.0.0, and ^0.4.5 expands to the range >= 0.4.5 < 0.5.0.

Using Flow From the Command Line

Flow is a client-server program. A Flow server must be running, and the client connects to it (or starts it if it's not running). The Flow CLI has many commands and options that are useful for maintenance and introspection purposes as well as for temporarily overriding configuration from .flowconfig.

Typing flow --help shows all the commands and options. To get help on a specific command, type flow <command> --help. For example:

Important commands are:

  • init: generate an empty .flowconfig file
  • check: do a full Flow check and print the results 
  • ls: display files visible to Flow
  • status (default): show current Flow errors from the Flow server
  • suggest: suggest types for the target file

Linting With Flow

Flow has a linting framework that can be configured via the .flowconfig file as you saw earlier, through command-line arguments, or in code files using flowlint comments. All configuration methods consist of a list of key-value pairs where the key is a rule and the value is the severity. 


There are currently three rules: all, untyped-type-import, and sketchy-null. The "All" rule is really the default handling for any errors that don't have a more specific rule. The "untyped-type-import" rule is invoked when you import a type from an untyped file. The "sketchy-null" rule is invoked when you do existence check on a value that can be false or null/undefined. There are more granular rules for:

  • sketchy-null-bool
  • sketchy-null-number
  • sketchy-null-string
  • sketchy-null-mixed

Severity Levels

There are also three severity levels: off, warning, and error. As you can imagine, "off" skips the type check, "warn" produces warnings, which don't cause the type check to exit and don't show up by default in the CLI output (you can see them with --include-warnings), and "error" is handled just like flow errors and causes the type check to exit and display an error message.

Linting With Command-Line Arguments

Use the --lints command-line argument to specify multiple lint rules. For example:

flow --lints "all=warn, untyped-type-import=error, sketchy-null-bool=off"

Linting With flowlint Comments

There are three types of comments: flowlint, flowlint-line, and flowlint-next-line.

The "flowlint" comment applies a set of rules in a block until overridden by a matching comment:

If there is no matching comment, the settings simply apply until the end of the file.

The "flowlint-line" applies just to the current line:  

The "flowlint-next-line" applies to the line following the comment:


Large JavaScript projects developed by large teams can benefit a lot from static type checking. There are several solutions for introducing static type checking into a JavaScript codebase. 

JavaScript continues to grow in a variety of ways across the web. It’s not without its learning curves, and there are plenty of frameworks and libraries to keep you busy, as you can see. If you’re looking for additional resources to study or to use in your work, check out what we have available in the Envato marketplace.

Facebook's Flow is a recent and robust solution with excellent coverage, tooling, and documentation. Give it a try if you have a large JavaScript codebase.

Source: Tuts Plus

About the Author