This post is for skeptics and newcomers to type systems, and aims to articulate rather than hard sell.

1. First we'll look at how static type conventions appear in your dynamically typed coding.
2. Then we'll step back and try to think about what this phenomenon tells us about how we want to code.
3. Lastly, we'll ask some (leading!) questions that should arise from these insights.

1A: Types in Names

Regardless of language, your journey with types starts almost as soon as you learn to code. The basic list data structure invites a corresponding plural:

var dog = 'Fido'
var dogs = ['Fido', 'Sudo', 'Woof']

As you work with more and more and more code, you start to form opinions that you may mandate to your team or style guide:

• always use specific names like dogID vs dogName vs dogBreed or a namespace/class/object like dog.name or dog.id or dog.breed
• singles should not be substrings of plurals, e.g. BAD: blog and blogs, GOOD: blogPost vs blogList
• booleans should have a boolean-ish prefix, like isLoading, hasProperty, didChange
• functions with side effects should have verbs
• internal variables should have a _prefix

This may seem trivial since we're talking about variable names, but this vein runs extremely deep. Names in our coding reflect the concepts and constraints we place on our code to make it more maintainable at scale:

• Presentational Components vs Stateful/Connected Containers
• Atoms, Molecules, Organisms, Templates, Pages
• Concepts, Actions, Operands (one of the most successful name grammars ever)
• Block__Element--Modifier
• Higher Order Components

These all seep into your code accordingly: *Container, *Component, *Reducer, *Template, *Page, with*.

Once you start crossing execution paradigms, you start feeling your way into monadic type hints.

Node.js felt this early on:

fs.readFile(myfile, callback)
fs.readFileSync(myfile) // introduced when people realized callback hell might not be worth non-blocking

React introduced the use prefix to indicate hooking into the runtime that must respect certain rules:

function Component() {
  const [bool, setBool] = React.useState(true)
  React.useEffect(callback)
  const foo = useCustomHook()
  // ...
}

I am personally fond of reminders of nullability:

const maybeResult = await fetchAPI()
if (maybeResult) {
  const result = maybeResult
  // do things with result
} else {
  // maybeResult is falsy, dont assume it is there
}

In almost everything you name, you're already using types.

So what, you ask?

Keep reading, I'm building up to it.

1B: Types in Data Structures

The problem with encoding types in names is that the language probably doesn't care about your meticulously named variables (indeed, in JavaScript, it probably gets mercilessly minified beyond recognition). It will happily run your code and throw a runtime error if you forget to respect your own nametypehints. What if we made types formally checkable through data structures?

The most basic are constants. In Redux, it is common to explicitly (and redundantly) set SCREAMING_CASE_CONSTANTS:

const ADD_TODO = 'slice/ADD_TODO'

// later in redux code:
import { ADD_TODO } from './redux/types'
switch (action.type) {
  case ADD_TODO:
  // do stuff based on the action
  // ...
}

This is mostly done because you can't trust your fellow developer not to typo their strings.

However even these strings offer too much trust, and we found it important enough to add a new language feature to guarantee uniqueness:

const ADD_TODO = Symbol('slice/ADD_TODO')

We also fake our way toward enums this way:

const colors = {
  BLUE: Symbol(1),
  GREEN: Symbol(2),
  RED: Symbol(3),
}

But simple values (strings, numbers, booleans) are actually easy to compare and treat accordingly.

More pressing is encoding types in complex values.

This usually happens when you have arrays of objects and the objects are different in some ways and similar in others:

const animals = [{ name: 'Fido', legs: 4, says: 'woof' }, { name: 'Kermit', legs: 2, marriedTo: 'Piggy' }]
// will have bugs if an animal with both `says` and `marriedTo` exists
animals.forEach((animal) => {
  if (animal.says) {
    // i guess it's a dog?
  }
  if (animal.marriedTo) {
    // i guess it's a frog?
  }
})

Buggy checking and implicitly assumed types is often a cause for much pain. Better to type explicitly:

const animals = [
  {
    type: 'dog', // new!
    name: 'Fido',
    legs: 4,
    says: 'woof',
  },
  {
    type: 'frog', // new!
    name: 'Kermit',
    legs: 2,
    marriedTo: 'Piggy',
  },
]
animals.forEach((animal) => {
  if (animal.type === 'dog') {
    // must be a dog!
  }
  if (animal.type === 'frog') {
    // must be a frog!
  }
})

This is in fact what happens for Redux (and, interestingly enough, handy for other things like Discriminated Unions), but you will see this everywhere in Gatsby and Babel and React and I'm sure you know of cases I don't.

Types even exist in HTML: <input type="file"> and <input type="checkbox"> behave so differently! (and I already mentioned Types in CSS with Block__Element--Modifier)

Even in HTML/CSS, you're already using types.

1C: Types in APIs

I'm almost done. Even outside your programming language, the interfaces between machines involve types.

REST's big innovation was basically a primitive form of typing client-server requests: GET, PUT, POST, DELETE. Web conventions have introduced other type fields in requests, like the accept-encoding header, that you must adhere to to get what you want. However, RESTfulness is basically not enforced, and because it doesn't offer guarantees, downstream tooling cannot assume properly behaved endpoints.

GraphQL takes that idea and dials it up to 11: Types are key to queries and mutations and fragments, but also on every field and every input variable, validated on both clientside and serverside by spec. With much stronger guarantees, it is able to ship much better tooling as a community norm.

I don't know the history of SOAP and XML and gRPC and other machine-machine communication protocols but I'm willing to bet there are strong parallels.

Part 2: What Does This Tell Us?

This was a very long, and yet inexhaustive examination of types permeating everything you do. Now that you've seen these patterns, you can probably think of more examples I'm forgetting right now. But at every turn, it seems the way toward more maintainable code, and better tooling is to add types in some way.

I mentioned parts of this thesis in How To Name Things, but basically all of the naming schemas fall under an enlightened form of Hungarian notation, as described in Joel Spolsky's Making Wrong Code Look Wrong.

If none of what I have described resonates with you, and isn't something you've already been doing, then types may not be for you.

But if it does, and you've been doing this in slipshod fashion, you may be interested in more structure around how you use types in your code, and in using better tooling that takes advantage of all the hard work you already put into types.

You may be working your way toward a type system, without even knowing it.

Part 3: Leading Questions

So knowing what we know now about using types in our code without a type system. I'll ask some hard questions.

Question 1: What do you currently do to enforce types without a type system?

At an individual level, you engage in defensive coding and manual verification. Basically manually eyeballing your own code and reflexively adding checks and guards without knowing if they're really needed (or, worse, NOT doing it and figuring out after seeing run time exceptions).

At a team level, you spend multiples of developer-hours in code review, inviting bike shedding over names, which we all know is great fun.

These two processes are manual methods, and a very poor use of developer time. Don't be the bad cop - this wrecks team dynamics. At scale, you are mathematically guaranteed to have lapses in code quality (therefore causing production bugs), either because everyone missed something, or there just wasn't enough time and you just had to ship something, or there wasn't a good enough policy in place yet.

The solution, of course, is to automate it. As Nick Schrock says, Delegate to Tooling Whenever Possible. Prettier and ESLint help to hold up your code quality - only to the extent to which the program can understand you based on an AST. It does not offer any help crossing function and file boundaries - if function Foo expects 4 arguments and you only pass it 3, no linter will yell at you and you'll have to defensively code inside Foo.

So there's only so much you can automate with a linter. What about the rest you can't automate?

Therein lies the last option: Do Nothing.

Most people do nothing to enforce their informally designed type systems.

Question 2: How much of these types are you writing yourself?

It goes without saying that if all your type policies are created by you, then they must be written by you and enforced by you.

That's totally different from how we write code today. We lean heavily on open source - 97% of modern web app code is from npm. We import shared code, and then write the last mile parts that make our app special (aka business logic).

Is there a way to share types?

(yes)

Question 3: What if your types were standardized?

Research has shown that the #1 reason programmers adopt a language is the existing capabilities and functionality available for them to use. I will learn Python to use TensorFlow. I will learn Objective C to create native iOS experiences. Correspondingly, JS has been so successful because it runs everywhere, compounded by the wide availability of free open source software written by other people. With some standardized type system, we can import types just as easily as we import open source software written by other people.

Just like GraphQL vs REST, Standardized types in a language unlock much better tooling. I will offer 4 examples:

Example 1: Faster Feedback

We might take months and days to learn from runtime errors, and these are exposed to users, so they are the worst possible outcome.

We write tests and apply lint rules and other checks to move these errors to build time errors, which shortens feedback cycles to minutes and hours. (As I wrote recently: Types don't replace Tests!)

Type Systems can shorten this feedback by yet another order of magnitude, to seconds, checking during write time. (Linters can also do this. Both are conditional on a supportive IDE like VS Code) As side effect, you get autocomplete for free, because autocomplete and write time validation are two sides of the same coin.

Example 2: Better Error Messages

const Foo = {
  getData() {
    return 'data'
  },
}
Foo['getdata']() // Error: undefined is not a function

JavaScript is intentionally lazy evaluation by design. Instead of the dreaded and nondescript undefined is not a function during runtime, we can move this to write time. Here's the write time error message for the exact same code:

const Foo = {
  getData() {
    return 'data'
  },
}
Foo['getdata']() // Property 'getdata' does not exist on type '{ getData(): string; }'. Did you mean 'getData'?

Why yes, TypeScript, I did.

Example 3: Edge Case Exhaustion

let fruit: string | undefined
fruit.toLowerCase() // Error: Object is possibly 'undefined'.

Over and above the built in nullable checking (which takes care of issues like passing in 3 arguments when a function expects 4), a type system can make the most of your enums (aka union types). I struggled coming up with a good example but here is one:

type Fruit = 'banana' | 'orange' | 'apple'
function makeDessert(fruit: Fruit) {
  // Error: Not all code paths return a value.
  switch (fruit) {
    case 'banana':
      return 'Banana Shake'
    case 'orange':
      return 'Orange Juice'
  }
}

Example 4: Fearless Refactoring

Many people mentioned this and I'll be honest that it took me a long while to come around to this. The thinking is: "so what? I don't refactor that much. so that means TypeScript's benefit is smaller to me than to you because I'm better than you."

This is the wrong take.

When we start off exploring a problem, we start off with a vague idea of the solution. As we progress, we learn more about the problem, or priorities change, and unless we've done it a million times we probably picked something wrong along the way, whether it be function API, data structure, or something larger scale.

The question is then to either stick with it until it breaks or to refactor the moment you can sense that you're going to outgrow whatever you used to have. I'll assume you accept that there are often benefits to refactoring. So why do we avoid refactoring?

The reason you put off that refactor is that it is costly, not because it isn't beneficial to you. Yet putting it off only increases future cost.

Type System tooling helps to dramatically lower the cost of that refactor, so you can experience the benefits earlier. It lowers that cost via faster feedback, exhaustiveness checking, and better error messages.

Truth in Advertising

There is a cost to learning Type Systems you didn't write. This cost may offset any imagined benefit to automated type checking. This is why I put a great deal of effort into helping to lower that learning curve. However, be aware that it is a new language and will involve unfamiliar concepts, and also that even the tooling is an imperfect work in progress.

But it is good enough for AirBnb and Google and Atlassian and Lyft and Priceline and Slack and it may be for you.

As a JavaScript developer, you can code all day long without encountering any static types. So why bother learning about them?

Well it turns out learning types isn’t just an exercise in mind-expansion. If you’re willing to invest some time in learning about static types’ advantages, disadvantages, and use cases, it could help your programming immensely.

Interested? Well you’re in luck — that’s what the rest of this four-part series is about.

First, a definition

The quickest way to understand static types is to contrast them with dynamic types. A language with static types is referred to as a statically-typed language. On the other hand, a language with dynamic types is referred to as a dynamically-typed language.

The core difference is that statically-typed languages perform type checking at compile time, while dynamically-typed languages perform type checking at runtime.

This leaves one more concept for you to tackle: what does “type-checking” mean?

To explain, let’s look at types in Java versus Javascript.

“Types” refers to the type of data being defined.

For example, in Java if you define a boolean as:

boolean result = true;

This has a correct type, because the boolean annotation matches the value given to result, as opposed to an integer or anything else.

On the other hand, if you tried to declare:

boolean result = 123;

…this would fail to compile because it has an incorrect type. It explicitly marks result as a boolean, but then defines it as the integer 123.

JavaScript and other dynamically-typed languages have a different approach, allowing the context to establish what type of data is being defined:

var result = true;

Long story short: statically-typed languages require you to declare the data types of your constructs before you can use them. Dynamically-typed languages do not. JavaScript implies the data type, while Java states it outright.

So as you can see, types allow you to specify program invariants, or the logical assertions and conditions under which the program will execute.

Type-checking verifies and enforces that the type of a construct (constant, boolean, number, variable, array, object) matches an invariant that you’ve specified. You might, for example, specify that “this function always returns a string.” When the program runs, you can safely assume that it will return a string.

The differences between static type checking and dynamic type checking matter most when a type error occurs. In a statically-typed language, type errors occur during the compilation step, that is, at compile time. In dynamically-typed languages, the errors occur only once the program is executed. That is, at runtime.

This means that a program written in a dynamically-typed language (like JavaScript or Python) can compile even if it contains type errors that would otherwise prevent the script from running properly.

On the other hand, if a program written in a statically-typed language (like Scala or C++) contains type errors, it will fail to compile until the errors have been fixed.

A new era of JavaScript

Because JavaScript is a dynamically-typed language, you can go about declaring variables, functions, objects and anything without declaring the type.

Convenient, but not always ideal. Which is why tools like Flow and TypeScript have recently stepped in to give JavaScript developers the option to use static types.

Flow is an open-source static type checking library developed and released by Facebook that allows you to incrementally add types to your JavaScript code.

TypeScript, on the other hand, is a superset that compiles down to JavaScript — although it feels almost like a new statically-typed language in its own right. That said, it looks and feels very similar to JavaScript and isn’t hard to pick up.

In either case, when you want to use types, you explicitly tell the tool about which file(s) to type-check. For TypeScript you do this by writing files with the .ts extension instead of .js. For Flow, you include a comment on top of the file with @flow

Once you’ve declared that you want to type-check a file, you get to use their respective syntax for defining types. One distinction to make between the two tools is that Flow is a type “checker” and not a compiler. TypeScript, on the other hand, is a compiler.

I truly believe that tools like Flow and TypeScript present a generational shift and advancement for JavaScript.

Personally, I’ve learned so much by using types in my day-to-day. Which is why I hope you’ll join me on this short and sweet journey into static types.

The rest of this 4-part post will cover:

Part I. A quick intro to the Flow syntax and language

Parts II & III. Advantages & Disadvantages of static types (with detailed walk-through examples)

Part IV. Should you use static types in JavaScript or not?

Note that I chose Flow over TypeScript in the examples in this post because of my familiarity with it. For your own purposes, please do research and pick the right tool for you. TypeScript is also fantastic.

Without further ado, let’s begin!

Part 1: A quick intro to Flow syntax and language

To understand the advantages and disadvantages of static types, you should first get a basic understanding of the syntax for static types using Flow. If you’ve never worked in a statically-typed language before, the syntax might take a little while to get used to.

Let’s begin by exploring how to add types to JavaScript primitives, as well as constructs like Arrays, Object, Functions, and etc.

boolean

This describes a boolean (true or false) value in JavaScript.

Notice that when you want to specify a type, the syntax you use is:

number

This describes an IEEE 754 floating point number. Unlike many other programming languages, JavaScript doesn’t define different types of numbers (like integers, short, long, and floating points). Instead, numbers are always stored as double precision floating point numbers. Hence, you only need one number type to define any number.

number includes Infinity and NaN.

string

This describes a string.

null

This describes the null data type in JavaScript.

void

This describes the undefined data type in JavaScript.

Note that null and undefined are treated differently. If you tried to do:

Flow would throw an error because the type void is supposed to be of type undefined which is not the same as the type null.

Array

Describes a JavaScript array. You use the syntax Array<;T> to describe an array whose elements are of some type T.

Notice how I replaced T with string, which means I’m declaring messages as an array of strings.

Object

This describes a JavaScript object. There are a few different ways to add types to objects.

You could add types to describe the shape of an object:

You could define objects as maps where you map a string to some value:

You could also define an object as an Object type:

This last approach lets us set any key and value on your object without restriction, so it doesn’t really add much value as far as type-checking is concerned.

any

This can represent literally any type. The any type is effectively unchecked, so you should try to avoid using it unless absolutely necessary (like when you need to opt out of type checking or need an escape hatch).

One situation you might find any useful for is when using an external library that extends another system’s prototypes (like Object.prototype).

For example, if you are using a library that extends Object.prototype with a doSomething property:

You may get an error:

To circumvent this, you can use any:

Functions

The most common way to add types to functions is to add types to it’s input arguments and (when relevant) the return value:

You can even add types to async functions (see below) and generators:

Notice how our second parameter getPurchaseLimit is annotated as a function that returns a Promise. And amountExceedsPurchaseLimit is annotated as also returning a Promise.

Type alias

Type aliasing is one of my favorite ways to use static types. They allow you to use existing types (number, string, etc.) to compose new types:

Above, I created a new type called PaymentMethod which has properties that are comprised of number and string types.

Now if you want to use the PaymentMethod type, you can do:

You can also create type aliases for any primitive by wrapping the underlying type inside another type. For example, if you want to type alias a Name and EmailAddress:

By doing this, you’re indicating that Name and Email are distinct things, not just strings. Since a name and email aren’t really interchangeable, doing this prevents you from accidentally mixing them up.

Generics

Generics are a way to abstract over the types themselves. What does this mean?

Let’s take a look:

I created an abstraction for the type T. Now you can use whatever type you want to represent T. For numberT, T was of type number. Meanwhile, for arrayT, T was of type Array<number>.

Yes, I know. It’s dizzying stuff if this is the first time you’re looking at types. I promise the “gentle” intro is almost over!

Maybe

Maybe type allows us to type annotate a potentially null or undefined value. They have the type T|void|null for some type T, meaning it is either type T or it is undefined or null. To define a maybe type, you put a question mark in front of the type definition:

Here I’m saying that message is either a string, or it’s null or undefined.

You can also use maybe to indicate that an object property will be either of some type T or undefined:

By putting the ? next to the property name for middleInitial, you can indicate that this field is optional.

Disjoint unions

This is another powerful way to model data. Disjoint unions are useful when you have a program that needs to deal with different kinds of data all at once. In other words, the shape of the data can be different based on the situation.

Extending on the PaymentMethod type from our earlier generics example, let’s say that you have an app where users can have one of three types of payment methods. In this case, you can do something like:

Then you can define your PaymentMethod type as a disjoint union with three cases.

Payment method now can only ever be one of these three shapes. The property type is the property that makes the union type “disjoint”.

You’ll see more practical examples of disjoint union types later in part II.

All right, almost done. There are a couple other features of Flow worth mentioning before concluding this intro:

1) Type inference: Flow uses type inference where possible. Type inference kicks in when the type checker can automatically deduce the data type of an expression. This helps avoid excessive annotation.

For example, you can write:

Even though this Class doesn’t have types, Flow can adequately type check it:

Here I’ve tried to define area as a string, but in the Rectangle class definition we defined width and height as numbers. So based on the function definition for area, it must be return a number. Even though I didn’t explicitly define types for the area function, Flow caught the error.

One thing to note is that the Flow maintainers recommend that if you were exporting this class definition, you’d want to add explicit type definitions to make it easier to find the cause of errors when the class is not used in a local context.

2) Dynamic type tests: What this basically means is that Flow has logic to determine what the the type of a value will be at runtime and so is able to use that knowledge when performing static analysis. They become useful in situations like when Flow throws an error but you need to convince flow that what you’re doing is right.

I won’t go into too much detail because it’s more of an advanced feature that I hope to write about separately, but if you want to learn more, it’s worth reading through the docs.

We’re done with syntax

We covered a lot of ground in one section! I hope this high-level overview has been helpful and manageable. If you’re curious to go deeper, I encourage you to dive into the well-written docs and explore.

With syntax out of the way, let’s finally get to the fun part: exploring the advantages and disadvantages of using types!

Next up: Part 2 & 3.

Flow is a static type checker for JavaScript. It makes you more productive by providing feedback as you write code. Flow gives you warnings in real-time that point out when you’ve made a mistake. If you would like to know more, check out flowtype.org.

Rather than trying to build it’s own entirely separate ecosystem, Flow hooks into the existing JavaScript ecosystem. Using Babel to compile your code is one of the easiest ways to integrate Flow into a project.

After two years of hard work, Babel works pretty much everywhere, just take a look at the setup page with integrations for every build tool you can imagine.

If you don’t have Babel set up yet, you can use that guide to get set up. You also might want to checkout my handbook on Babel.

Setting up Flow on top of Babel

Once you have Babel set up, it’s easy to get going with Flow. First lets install two dependencies:

$ npm install --save-dev babel-plugin-transform-flow-strip-types$ npm install --global flow-bin

The Babel plugin is there in order to strip Flow types away so that your program runs. flow-bin is how you use Flow from the command line.

Next, let’s add the Babel plugin to your .babelrc (or where-ever you are configuring Babel with options):

{  presets: [...],  plugins: [..., "transform-flow-strip-types"]}

Note: I’m assuming you are using Babel 6 for this tutorial. It is recommended that you upgrade if you have not already.

Finally we’ll run flow init in our directory, which will create a .flowconfig file that should look like this:

[ignore]

[include]

[libs]

[options]

Awesome! Now we have Flow all set up in your project. How about we start making it run on some files?

Getting Flow running

Flow is designed to be introduced to your repo incrementally. That means that you don’t have to add it to your whole codebase all at once. Instead, you can add it file-by-file as you go. Let’s start with something simple to get you going.

First, try to find a file that doesn’t have a lot of complexity or external dependencies. Something with just a handful of plain functions to get started with.

import {getNumberFromString} from "string-math-lib";

export function multiplyStrings(a, b) {  return getNumberFromString(a) * getNumberFromString(b);}

In order to get Flow running on this file, we need to add a “flow pragma” comment at the top like this:

// @flow

import {getNumberFromString} from "string-math-lib";

export function multiplyStrings(a, b) {  return getNumberFromString(a) * getNumberFromString(b);}

This little comment at the top of the file tells Flow “Okay, I want you to type-check this file”.

Now we need to actually run Flow for the first time. In order to do that, you’ll need to switch back to your terminal and run the following command:

$ flow

Note: This command is an alias of flow status.

What this command does is start up a Flow server and asks it for the “status” of your repo, which will most likely return some errors for you to fix.

The most common errors that you’re gonna see in a new file are:

• “Missing annotation”
• “Required module not found”

These errors are related to imports and exports. The reason they come up is a result of how Flow works. In order to check types across files, Flow looks directly at the imports and exports of each file.

“Missing annotation”

You’ll see an error like this from Flow because it relates somehow to an export of your file. Other than that Flow won’t complain about missing type annotations.

So in order to fix that, we can start adding some types to your file. For a detailed guide on how to do that see the user guide. What you should end up is with some types like this:

import {getNumberFromString} from "string-math-lib";

export function multiplyStrings(a: string, b: string): number {  return getNumberFromString(a) * getNumberFromString(b);}

Keep running flow as you add your types to see the effects of what you are doing. Eventually you should be able to clear out all the “Missing annotation” errors.

“Required module not found”

You’ll get these errors whenever you an import/require that can’t be resolved using Node’s normal module algorithm or if you have ignored it with your .flowconfig.

This can be caused by a lot of things, maybe you’re using a special webpack resolver, maybe you forgot to install something. Whatever the reason, Flow needs to be able to find the module you are importing to do its job correctly. You have a couple options on how to solve this:

1. module.name_mapper — specify a regular expression to match against module names, and a replacement pattern.
2. Create a library definition for the missing module

We’ll focus on creating a library definition for the module, if you need to use module.name_mapper you can see more about it in the documentation.

Creating a library definition

Having library definitions is useful for giving types to the packages you have installed that don’t have types. Let’s set one up for our string-math-lib library from the previous example.

First create a flow-typed directory in your root directory (the directory where you put your .flowconfig).

You can use other directory names using the [lib] section of your .flowconfig. However, using flow-typed will work out of the box.

Now we’ll create a flow-typed/string-math-lib.js file to hold our “libdef” and start it off like this:

declare module "string-math-lib" {  // ...}

Next we just need to write definitions for exports of that module.

declare module "string-math-lib" {  declare function getNumberFromString(str: string): number}

Note: If you need to document the “default” or primary export, you can do that with declare module.exports: or declare export default

There’s a lot more to library definitions so you should read through the documentation and read this blog post on how to create high-quality libdefs.

Installing a libdef from flow-typed

Because libdefs can consume a lot of time, we maintain an official repository of high-quality libdefs for all sorts of packages called flow-typed.

To get started with flow-typed, install the command line interface (CLI) globally:

$ npm install --global flow-typed

Now you can look within flow-typed/definitions/npm to see if there’s an existing libdef for a package you want to use, if there is you can install it like this:

$ flow-typed install chalk@1.0.0 --flowVersion 0.30

This tells flow-typed that you want to install the chalk package at the 1.0.0 version when you are running Flow 0.30.

The flow-typed CLI is still in beta and there is a lot of improvements planned for it, so expect this to improve a lot in the near future.

Be sure to contribute back to the flow-typed libdefs. It’s a community effort, and the more people that contribute, the better it gets.

Other errors you might run into:

Hopefully, we’ve covered just about everything that you will run into while getting started with Flow. However, you also might run into some errors like this:

• Package inside of node_modules is reporting errors
• Reading node_modules is taking a really long time
• Malformed JSON inside node_modules is causing errors

There’s a handful of reasons for these types of errors that I won’t get into in this post (I’m working on detailed documentation for each individual error). For now, in order to keep yourself moving, you can just [ignore] the files that are causing these errors.

This means adding file paths to your [ignore] section in your .flowconfig like this:

[ignore]./node_modules/package-name/*./node_modules/other-package/tests/*.json

[include]

[libs]

[options]

There is generally better options than this, but this should give you a good place to start.

For some examples of how to better handle errors within node_modules see this Stack Overflow answer about fbjs.

Pro tip: Checking to see how well you’re covered

If you’re ever wondering how well a file is covered by Flow, you can use the following command to see a coverage report:

$ flow coverage path/to/file.js --color

Additional Resources and Support

There’s lots that was not covered by this article. So here are some links to resources that can help you out.

• Flow Website
• Try Flow Online
• Flow GitHub
• Stack Overflow #flowtyped

The Flow team is committed to making sure that everyone has an excellent experience using Flow. If that is ever not true, we’d love to hear from you about how to improve.

Follow James Kyle on twitter. Follow Flow on twitter too.