flow-typed: library definitions for Flow projects, and when the CLI is worth the install

The gap flow-typed fills: untyped npm packages in a Flow codebase

Flow only checks code it can see types for. When you import a library that was not written with Flow, the README states that Flow ignores it, leaving it untyped. The practical consequence is concrete: no error when you call a function with the wrong arguments, and no autocomplete for the library's API. Flow's answer is library definitions, or libdefs, which describe a module's interface separately from its implementation. flow-typed is the distribution channel for those definitions. It is aimed at teams that have already committed to Flow as their type checker and now need coverage for the dependencies they pull from npm. It is not a type checker itself, and it does not generate types from source. The repository holds the definitions; the npm package holds the CLI that fetches them.

How flow-typed works: a definitions repo, a CLI and a checked-in flow-typed directory

The mechanism is a lookup, not a transformation. The definitions/ directory in the repository contains libdefs contributed by the community and reviewed through pull requests. When you run the CLI's install command, it inspects your project's dependencies and downloads the libdefs that match them into a flow-typed directory inside your project. The README's instruction is to check those files in, which means the definitions become part of your repository rather than something fetched at build time. That design has a clear consequence: upgrades to a libdef arrive as a diff in your own history, so a definition change is reviewable alongside the code that depends on it. The repository also contains tests for the definitions, and the README describes the repo as definitions plus tests plus tooling, so quality control happens upstream in the project's own CI rather than in your checkout.

Installing the flow-typed CLI and running your first install

The CLI is published on npm as flow-typed. The README points to the quick start page in the docs at flow-typed.github.io/flow-typed, which covers installing typedefs, using them, and writing your own. The repository also ships build and test scripts at the top level, including build_and_test_cli.sh and quick_run_def_tests.sh, which are for working on the project itself rather than for consuming it. Once the CLI is available, the command the README names for pulling definitions into a project is flow-typed install:

flow-typed install

According to the README, this searches the libdef repo and downloads all the libdefs relevant to your project, installing them for you. The next step it describes is simply checking them in, so after the command runs you should expect a flow-typed directory in your project containing the downloaded definitions, ready to be committed.

If you want to inspect the command surface before running anything, the README says the full list of commands is in the install page of the docs. That is the place to look for flags and subcommands, because the README itself does not enumerate them.

Where flow-typed stops helping: missing definitions and stale versions

The lookup model fails in a predictable way. If no definition exists for a dependency, or the existing definition was written for a different major version than the one you installed, the CLI has nothing correct to hand you. The README does not document what the CLI does in that case, so the behaviour on a miss is something to confirm against the docs rather than assume. This matters most for fast-moving libraries: a libdef is a separate artifact from the package it describes, and it can lag. The README's note says the project's focus includes keeping type definitions up to date, which is an acknowledgement that staleness is the ongoing problem. If your stack is dominated by small, rapidly versioned packages, expect to write or patch libdefs yourself rather than receive them. The repository's CONTRIBUTING.md and the create_def.sh script exist for exactly that path: contributing a definition back through a pull request.

flow-typed compared with TypeScript's DefinitelyTyped model

The closest structural analogue is DefinitelyTyped, the community definitions repository for TypeScript, and the difference is worth stating plainly because it shapes day-to-day work. In the DefinitelyTyped model, definitions are published as separate @types packages on npm, so they flow through the same dependency resolution, versioning and lockfile machinery as everything else. In flow-typed, the CLI copies definitions into a flow-typed directory in your repository and the README tells you to check them in. That means the definitions are yours to maintain once installed: no transitive resolution, no automatic bump when a definition improves upstream, and a diff in your own pull requests whenever you refresh. The trade-off is deliberate. A checked-in libdef is auditable and immune to a registry outage, but it also means the update is a task you own rather than a version range you widen. If you want definitions to behave like ordinary dependencies, the npm-published model is the one you are looking for.

Maintenance status and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-13. The most recent release listed is v4.1.1 from 2025-05-13, following v4.1.0 in April 2025 and v4.0.0 in May 2024. The README carries a note from the maintainers stating that activity has slowed in recent months, that they are committed to maintaining functionality and fixing issues that arise with new Flow releases, and that no major new features are planned, though feature contributions are welcome. Read that as a stability commitment rather than a roadmap. The upgrade cost has two parts. The CLI itself moves slowly, so bumping it is rarely the expensive step. The recurring cost is the definitions: each time you add or upgrade a dependency, you re-run the install command and review the resulting diff in the checked-in flow-typed directory. The repository is MIT licensed, and the definitions you commit carry that licence with them, so if you redistribute them you should read the LICENSE file in the repository rather than take a summary as authoritative. Nothing here is legal advice; the licence text is the source.

Contributing a libdef when the one you need does not exist

The README's answer to a missing definition is a pull request, and it points at CONTRIBUTING.md for the process and best practices. The repository layout supports that workflow directly: definitions/ holds the libdefs, create_def.sh scaffolds a new one, and quick_run_def_tests.sh plus test_harness.sh run the definition tests locally. CONTRIBUTING.md is the document to read before opening a pull request, and the README says it gives a detailed overview of how to raise one following the project's best practices. For CLI changes the README draws a line: bugfixes and improvements are welcome, but new features should start as an issue for discussion first. That distinction is worth respecting, because a pull request for an unplanned feature is more likely to sit than one that fixes a reported problem.

Editorial conclusion

Adopt flow-typed if your project already runs Flow and you depend on untyped npm packages, because flow-typed install pulls the matching libdefs into flow-typed/ and you check them in. Do not adopt it if you are choosing a type system from scratch or expect active feature development: the README says major new features are not planned and activity has slowed, though the last push was on 2026-09-13. Before relying on it, verify that definitions exist for your exact dependency versions and check the MIT licence text in the repository for how you may redistribute the libdefs you commit.

Frequently asked questions

Official sources

1. flow-typed/flow-typed on GitHub
2. License: MIT
3. Project website
4. README
5. Releases