Notice: Currently the flow-typed CLI is not up-to-date, nor is it particularly useful. The CLI is still underway and will be published to npm when it's ready.

flow-typed is a repository of third-party library interface definitions for use with Flow.

Huh?

When you start a project with Flow, you might want to use some third-party libraries that were not written with Flow. Flow is usually able to work it's way around this, but at the unfortunate cost of typing those third-party modules as any. As a result, Flow can't give errors if you accidentally mis-use the library (nor will it be able to auto-complete the library).

To address this, Flow supports library definitions which allow you to describe the interface of a module or library separate from the implementation of that module/library.

The flow-typed repo is a collection of high-quality library definitions, tests to ensure that they remain high quality, and tooling to make it as easy as possible to import them into your project.

How Do I Contribute?

Just send a pull request!

All definitions sit under the /definitions folder. They all must follow the following naming format:

<NPM_PACKAGE_NAME>_v<VERSION>/flow_v<VERSION>/<NPM_PACKAGE>_v<VERSION>.js

Where <VERSION> is a semver version number with all of MAJOR, MINOR, and PATCH version numbers included. x is an acceptable wildcard in place of any of the three version numbers, and it is also acceptable to put >= or <= in front of the v to indicate a range of versions.

Example filename:

underscore_v1.x.x/flow_>=v0.13.x/underscore_v1.x.x.js

This is a library definition for all "1.x.x" versions of underscore that works with any version of Flow >= v0.13.

We structure files this way is to enable automated testing and tooling. Tests ensure that library definitions continue to work as expected and the flow-typed tooling ensures that it's as easy as possible to find and install library definitions.

Writing Tests

When you contribute a new library definition (or make a change to an existing one), you should include tests with your change.

Tests are simply test-*.js files that sit next to the library definition file. Their purpose is to exercise the defined library and ultimately produce zero Flow errors for each version of Flow that the libdef is specified as compatible with.

Often it is useful to test that a particular usage of a library definition does produce an error. For this you can write some code that produces a Flow error and just put // $ExpectError on the line above where the error is produced. This will tell the test runner that an error is intentional and expected on the following line.

flow-typed CLI

The flow-typed npm package provides a CLI that provides several commands for working with this repository:

flow-typed validate-defs

Verifies that all files under the /definitions/ directory are structured properly. It does not run tests, it only asserts that file and directory names match the expected conventions.

flow-typed run-tests [optional-pattern]

Runs all compatible versions of Flow over the each library definition with it's tests to ensure that the tests pass as expected.

Note that this command assumes that the /definitions/ directory is correctly structured. You can always verify the structure with the flow-typed validate-defs command.

(...coming soon...) flow-typed libdefs-for-pkg /path/to/package.json

Scans the specified package.json, looks for any compatible libdefs in the flow-typed github repo, and prints a JSON list of URLs for each that is found.