Getting started with Flow
To demonstrate how to add Flow to a project, let’s set up an example npm project.
First, we’ll make an npm package for our example project called “get_started”:
$> mkdir -p get_started
$> cd get_started
$> echo '{"name": "get_started", "scripts": {"flow": "flow; test $? -eq 0 -o $? -eq 2"}}' > package.json
Next we’ll add Flow to our project:
$> touch .flowconfig
$> npm install --save-dev flow-bin
And now we can start writing some code!
index.js
// @flow
var str = 'hello world!';
console.log(str);
Note that we’ve added // @flow
to the top of our file. This indicates to Flow
that we want this file to be checked. If we don’t add this flag to the top of
the file, Flow will assume that the file isn’t ready to be checked yet and
Flow will not attempt to type check the file.
Ok, now let’s run Flow and see what it has to say about the code we just wrote:
$> npm run-script flow
> test@ flow /get_started
> flow
No errors!
Woohoo! No errors! Ok, now let’s add a trivial type error just to see what happens:
index.js
// @flow
var str: number = 'hello world!';
console.log(str);
$> npm run-script flow
> test@ flow /get_started
> flow 2> /dev/null
index.js:3
3: var str: number = 'hello world!';
^^^^^^^^^^^^^^ string. This type is incompatible with
3: var str: number = 'hello world!';
^^^^^^ number
Found 1 error
Cool – Flow noticed that we’re assigning a string to a number and gave an error.
Before we fix this type error, let’s add Babel to our project so we can try running our code:
$> npm install -g babel-cli
$> npm install --save-dev babel-plugin-transform-flow-strip-types
$> echo '{"plugins": ["transform-flow-strip-types"]}' > .babelrc
Now we can try running our code in spite of the type error and see what happens:
$> babel-node index.js
hello world!
It works! As you can see Flow does not prevent you from running the code you have written even if there are type errors. It is considered best practice to never publish your project when it has type errors, but often at development time it’s useful to try running code even before it fully typechecks (usually for debugging or ad-hoc testing). This is one of the benefits of gradual typing and Flow is designed to support this and stay out of your way as much as you need it to during development.
Note that we ran our code using babel-node
rather than just vanilla node
to
run index.js. babel-node
comes with babel-cli
and is just a thin wrapper around vanilla node
that
first intercepts and transpiles JS code before running it with node
.
Check out the Running Flow Code section for more details on how we recommend compiling and publishing Flow code to npm and into production.
Next steps#
Now that we know how to set Flow up, let’s take a quick look at a few examples that are included in the Flow repo:
You can edit this page on GitHub and send us a pull request!