Skip to main content

Getting Started

Flow is a static type checker for your JavaScript code. It helps you code faster, smarter, more confidently, and at a bigger scale.

Flow checks your code for errors through static type annotations. These types allow you to tell Flow how you want your code to work, and Flow will make sure it does work that way.

1function square(n: number): number {2  return n * n;3}4
5square("2"); // Error!incompatible-typeCannot call square with "2" bound to n because string [1] is incompatible with number [2].

Installation​

Setup Compiler​

First you'll need to setup a compiler to strip away Flow types. You can choose between Babel and flow-remove-types.

Babel is a compiler for JavaScript code that has support for Flow. Babel will take your Flow code and strip out any type annotations. If you already use Babel in your project, see using Babel.

First install @babel/core, @babel/cli, @babel/preset-flow, and babel-plugin-syntax-hermes-parser with either Yarn or npm.

npm install --save-dev @babel/core @babel/cli @babel/preset-flow babel-plugin-syntax-hermes-parser

Next you need to create a .babelrc file at the root of your project with the @babel/preset-flow preset and babel-plugin-syntax-hermes-parser plugin.

{
  "presets": ["@babel/preset-flow"],
  "plugins": ["babel-plugin-syntax-hermes-parser"]
}

If you then put all your source files in a src directory you can compile them to another directory by running:

./node_modules/.bin/babel src/ -d lib/

You can add this to your package.json scripts easily, alongside your "devDependencies" on Babel.

{
  "name": "my-project",
  "main": "lib/index.js",
  "scripts": {
    "build": "babel src/ -d lib/",
    "prepublishOnly": "yarn run build"
  }
}

Note: You'll probably want to add a prepublishOnly script that runs this transform as well, so that it runs before you publish your code to the npm registry.

Setup Flow​

Flow works best when installed per-project with explicit versioning rather than globally.

Luckily, if you're already familiar with npm or yarn, this process should be pretty familiar!

Add a devDependency on the flow-bin npm package​

npm install --save-dev flow-bin

Add a "flow" script to your package.json​

{
  "name": "my-flow-project",
  "version": "1.0.0",
  "devDependencies": {
    "flow-bin": "^0.309.0"
  },
  "scripts": {
    "flow": "flow"
  }
}

Run Flow​

The first time, run:

npm run flow init
> my-flow-project@1.0.0 flow /Users/Projects/my-flow-project
> flow "init"

After running flow with init the first time, run:

npm run flow
> my-flow-project@1.0.0 flow /Users/Projects/my-flow-project
> flow

No errors!

Setup Library Definitions​

Since version 0.263.0, most library definitions are no longer bundled with Flow. Instead, they are managed by flow-typed.

You should have a flow-typed.config.json in the root of your project with the following content:

{
  "env": ["node", "dom", "bom", "intl", "cssom", "indexeddb", "serviceworkers", "webassembly", "jsx"]
}

This tells flow-typed which environment definitions to include. You can adjust the list based on which environments your project targets.

Setup ESLint​

If you use ESLint, you can read our page on ESLint to set it up to support Flow.

Usage​

Initialize Your Project​

Preparing a project for Flow requires only one command:

flow init

Run this command at the top level of your project to create one, empty file called .flowconfig. At its most basic level, .flowconfig tells the Flow background process the root of where to begin checking Flow code for errors.

And that is it. Your project is now Flow-enabled.

It is common to have an empty .flowconfig file for your project. However, you can configure and customize Flow in many ways through options available to be added to .flowconfig.

Run the Flow Background Process​

The core benefit to Flow is its ability to quickly check your code for errors. Once you have enabled your project for Flow, you can start the process that allows Flow to check your code incrementally and with great speed.

flow status

This command first starts a background process that will check all Flow files for errors. The background process continues running, monitoring changes to your code and checking those changes incrementally for errors.

You can also type flow to accomplish the same effect as status is the default flag to the flow binary.

Only one background process will be running at any given time, so if you run flow status multiple times, it will use the same process.

To stop the background process, run flow stop.

Prepare Your Code for Flow​

The Flow background process monitors all Flow files. However, how does it know which files are Flow files and, thus, should be checked? Placing the following before any code in a JavaScript file is the flag the process uses to answer that question.

// @flow

This flag is in the form of a normal JavaScript comment annotated with @flow. The Flow background process gathers all the files with this flag and uses the type information available from all of these files to ensure consistency and error free programming.

You can also use the form /* @flow */ for the flag as well.

For files in your project without this flag, the Flow background process skips and ignores the code (unless you call flow full-check --all, which is beyond the scope of basic usage).

Write Flow Code​

Now that all the setup and initialization is complete, you are ready to write actual Flow code. For each file that you have flagged with // @flow, you now have the full power of Flow and its type-checking available to you. Here is an example Flow file:

1function foo(x: ?number): string {2  if (x) {3    return x;incompatible-typeCannot return x because number [1] is incompatible with string [2].4  }5  return "default string";6}

Notice the types added to the parameter of the function along with a return type at the end of the function. You might be able to tell from looking at this code that there is an error in the return type since the function can also return a number. However, you do not need to visually inspect the code since the Flow background process will be able to catch this error for you when you check your code.

Check Your Code​

The great thing about Flow is that you can get near real-time feedback on the state of your code. At any point that you want to check for errors, just run:

# equivalent to `flow status`
flow

The first time this is run, the Flow background process will be spawned and all of your Flow files will be checked. Then, as you continue to iterate on your project, the background process will continuously monitor your code such that when you run flow again, the updated result will be near instantaneous.

For the code above, running flow will yield:

3:12-3:12: Cannot return `x` because number is incompatible with string. [incompatible-type]