facebook/flow: a static typechecker for JavaScript that reports types as annotations

What Flow checks, and who is expected to run it

Flow is a static typechecker for JavaScript. It does not compile your code. It reads JavaScript files that carry type annotations and reports inconsistencies. The README states the goal directly: static typing to improve developer productivity and code quality. That framing matters, because it tells you the target user is someone with a large JavaScript codebase that cannot be rewritten in another language.

The practical audience is a team that already writes JavaScript and wants type errors surfaced before runtime without switching languages. Flow's annotations are comments in the source, so a file that passes Flow is still a JavaScript file that runs anywhere. The README describes the supported platforms as macOS on arm64, Linux on x86_64 and arm64, and Windows on x86_64 with Windows 10 recommended. Binary distributions exist for each, and the README says the project can also be built from source on any of them.

One detail in the README is easy to miss and shapes the tool's scope. Flow's parser is published to npm as flow-parser, a compiled-to-JavaScript module. The README says most end users will not need it directly, but JavaScript packages that parse Flow-typed JavaScript can use it to generate Flow's syntax tree with annotated types attached. That is a second product inside the same repository: a parser library for tool authors, not a checker for application developers.

How the checker and the Rust workspace fit together

The repository is a monorepo with a Rust workspace at rust_port/ and a JavaScript side under packages/, src/, newtests/, tests/, and website/. The README states plainly that Flow is written in Rust and that GitHub CI builds it from the rust_port workspace with nightly Rust. That is the first architectural fact worth knowing: the checker is a native binary, not a Node process.

The build files confirm the split. The root package.json is private and declares Yarn workspaces over newtests, packages/flow-dev-tools, and packages/flow-remove-types, with flow-remove-types marked nohoist. The Makefile defines a FLOW_JS_IMPL variable defaulting to rust-wasm, and only accepts that one value: any other setting produces an error reading "Unknown FLOW_JS_IMPL". So the JavaScript build of Flow is produced by compiling Rust to WebAssembly through Emscripten, not by a separate JavaScript implementation. The Makefile notes that the flow.js target runs scripts/build-flow-dot-js-wasm.sh, and that an optimized build is requested with make js FLOW_RELEASE=1.

The data flow for a user is short. You run the flow binary in a project, it parses the JavaScript files, attaches the annotations it finds, and reports type errors. The binary is the product. Everything else in the repository exists to build, test, or document that binary, or to expose its parser to other tools.

Installing Flow and running the checker for the first time

The README does not inline installation commands. It points to the installation instructions on flow.org and to the usage docs, so the canonical install path is the website rather than the repository. What the README does provide is the build-from-source route, which is useful when you want a specific revision or a platform the release binaries do not cover.

Building starts with the nightly Rust toolchain, because the README says CI builds Flow with nightly Rust.

rustup toolchain install nightly

From the repository root, move into the Rust workspace and build it. This compiles the workspace in debug mode, which the Makefile describes as faster to build but less efficient at runtime.

cd rust_port
cargo +nightly build

Running the tests in the same workspace checks that the toolchain and the checkout agree before you invest in a longer build.

cargo +nightly test

For a binary you would actually use day to day, build the release profile of the CLI target. The README names the binary target flow_cli.

cargo +nightly build --release --bin flow_cli

After that build, the compiled binary is what you run against a JavaScript project; the README does not list the checker's command-line flags, so consult the usage docs on flow.org for the invocation your project needs. If you need the WebAssembly build instead, the README pins a specific toolchain and target: nightly-2026-04-14 with wasm32-unknown-emscripten and the rust-src component, then make js FLOW_JS_IMPL=rust-wasm, which produces bin/flow.js. A development-profile variant is available by adding FLOW_DOT_JS_WASM_PROFILE=dev, which the README describes as faster and larger.

Where Flow is the wrong tool

The clearest limitation is stated by the README itself: most end users will not need flow-parser directly. If you arrived hoping for a drop-in JavaScript parser for a build plugin, the README is telling you that library exists but is aimed at packages that parse Flow-typed JavaScript. Using it for plain JavaScript parsing means carrying a dependency whose main job is attaching Flow annotations.

The second limitation is the build requirement for the WebAssembly artifact. The README pins Emscripten 3.1.44 and nightly-2026-04-14 for that build, and requires the wasm32-unknown-emscripten target plus the rust-src component. A pinned nightly toolchain is a maintenance obligation: the build instructions name a date-stamped compiler, so reproducing bin/flow.js later means reproducing that environment, not just running a current Rust install.

Third, the repository's own Makefile is a warning about build modes. FLOW_RELEASE defaults to the value of CI, and the comment says that without it you get dev mode, which builds faster but is less efficient at runtime. A release binary and a dev binary are not the same artifact, so a locally built checker can behave differently in performance terms from a downloaded one.

Finally, the checker is not a compiler. Flow reports type errors; it does not strip or transform your annotations for production. The repository does contain packages/flow-remove-types, which is the workspace entry whose name indicates that job, but the README does not describe it, so treat it as a separate tool to evaluate on its own rather than as part of the checker's documented surface.

Flow versus TypeScript: the actual difference in approach

TypeScript is the alternative most people weigh against Flow, and the difference is not just syntax. TypeScript is a language that compiles to JavaScript: you write .ts files, run a compiler, and ship the emitted JavaScript. Flow checks JavaScript as it is. The README's framing, a static typechecker for JavaScript, is the whole distinction. There is no emit step in the Flow path.

That changes how a codebase ages. With Flow, the files you check are the files you ship, and annotations are removable without losing runtime code. With TypeScript, the source and the artifact are different files, and the compiler sits in your build pipeline. Teams that already have a working JavaScript build and want type errors without adding a compiler stage are the ones Flow's design serves.

The second difference is ecosystem shape. Flow's parser is published to npm so other tools can consume its syntax tree; that is a deliberate integration point for tooling, not a type-definition registry. TypeScript's reach comes largely from its type declaration ecosystem, which the Flow README does not discuss at all. If your decision hinges on the availability of third-party type definitions, the README gives you no evidence either way, and that silence is itself a data point about where the project puts its documentation effort.

Licence, release cadence and what an upgrade costs

Flow is MIT-licensed, per the README and the LICENSE file at the repository root. The README adds a distinction that matters if you plan to republish documentation: the website and documentation are under the Creative Commons Attribution 4.0 licence, tracked in website/LICENSE-DOCUMENTATION. So the code and the docs carry different terms, and copying docs into your own material requires attribution that copying the code does not. This is a description of the licences, not legal advice; check the LICENSE file and your own counsel for your situation.

The release history shows a fast cadence. The three most recent releases are v0.329.0 on 2026-08-22, v0.328.0 on 2026-08-14, and v0.327.0 on 2026-08-12. Two releases eight days apart, then another two days later, means patch-level upgrades arrive frequently. The repository is not archived, and the last push was on 2026-08-22, the same day as the newest release.

That cadence sets the upgrade cost. There is no long-term support line mentioned in the README, and the version numbers are pre-1.0, so pinning a version and upgrading deliberately is the realistic policy. If your team cannot absorb a dependency that moves this often, the release list is the fact to weigh, not the feature set. The README also points to Changelog.md in the repository root for release notes, which is where the upgrade-specific detail lives; the README itself does not document rollback.

What to verify before you commit to Flow

Start with the install path. The README routes you to flow.org for installation and usage rather than giving commands, so the first check is whether the binary distribution for your platform exists in the releases and whether the usage docs describe the invocation your project needs. The README lists macOS arm64, Linux x86_64 and arm64, and Windows x86_64; anything outside that list means the source build.

If you plan to build rather than download, verify the toolchain before anything else. The Rust workspace needs nightly, and the WebAssembly build needs the dated nightly-2026-04-14 toolchain with wasm32-unknown-emscripten and rust-src. Confirm those are installable in your environment, because a pinned nightly is the part most likely to break a CI image.

If your interest is the parser rather than the checker, confirm that flow-parser on npm matches the Flow version you target. The README describes it as compiled-to-JavaScript and aimed at packages parsing Flow-typed JavaScript, so the compatibility question is yours to answer from the package's own metadata.

Finally, check the editor and tooling integration you depend on. The repository contains packages/flow-dev-tools, which the Makefile exercises with yarn --cwd packages/flow-dev-tools test, but the README does not describe what that package provides to end users. Anything you assume about editor support should be confirmed against flow.org, not against the repository listing.

Editorial conclusion

Flow fits teams with an existing Flow-annotated JavaScript codebase, or projects that want type checking without a compile step and are willing to keep annotations in the source. It does not fit greenfield projects that want the largest ecosystem of type definitions, or teams that need a compiler emitting JavaScript. Before adopting, verify three things: that your Node and build toolchain can consume flow-parser output if you plan to use it, that your editor integration is current, and that the release cadence of the version you pin matches your upgrade window. The repository is not archived and its last push was on 2026-08-22.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes