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 in versions
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:
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:
--write will update files that require annotations under
/path/to/folder in-place. Without this flag the resulting files will be printed on the command line.
--repeat ensures 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 info outputs 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 automatically.
© 2013–present Facebook Inc.
Licensed under the MIT License.