Prepare your codebase for Types-First
Upgrading to Types-First mode may require a substantial
number of type annotations at module boundaries. To help with the process of
upgrading large codebases, we are providing a codemod command, whose goal is to
fill in these missing annotations. This command is included in the Flow binary
Note: As of version 0.134, types-first is the default mode. If you are using a version
>=0.134, make sure you set
types_first=falsein your .flowconfig while running this codemod.
This command uses types that Flow infers, to fill in positions that would otherwise raise signature-verification failures. It will include the necessary type import statements, as long as the respective types are exported from their defining modules.
It is designed for use on multiple files at once, rather than one file at a time. For this reason it doesn’t connect to an existing Flow server, but rather starts a checking process of its own.
As is typical with such mechanized approaches, it comes with a few caveats:
- It won’t be able to fill in every required type annotation. Some cases will require manual effort.
- Inserted annotations may cause new flow errors, since it’s not always possible to match inferred type with types that can be written as annotations.
- File formatting may be affected. If a code formatter (e.g. prettier) is used, it is recommended that you run it after the codemod has finished running.
A typical way to invoke this command is
flow codemod annotate-exports \ --write \ --repeat \ --log-level info \ /path/to/folder \ 2> out.log
This command will transform files under
/path/to/folder. This does not need to
be the root directory (the one containing
It uses the following flags:
--writewill update files that require annotations under
/path/to/folderin-place. Without this flag the resulting files will be printed on the command line.
--repeatensures that the transformation will be applied until no more files change. This mode is necessary here, because each new type the codemod adds may require new locations to be annotated.
--log-level infooutputs useful debugging information in the standard error stream. This option might lead to verbose output, so we’re redirecting the error output to a log file
Another convenient way to provide the input is by passing the flag
file.txt contains a specific list of files to be transformed.
After each iteration of the codemod, a summary will be printed on the CLI. This summary includes statistical information about the number of annotations that were added, and how many locations were skipped. It also prints counts for various kinds of errors that were encountered. These can be matched to the errors printed in the logs.
A common error case is when a type
A, defined in a file
a.js, but not exported,
is inferred in file
b.js. The codemod will skip adding this annotation and report
an error in the logs. The fix this case, you can export
a.js. Note that
it is not necessary to manually import
b.js. The codemod will do this
Was this guide helpful? Let us know by sending a message to @flowtype.