Utility tools for Flow. Provides a few helpful functions like generating stubs and finding files that are not covered by Flow. Refer to the commands section for more.
If you have suggestions for further commands, feel free to create an issue.
$ npm install -g flow-scripts
$ flow-scripts <command> [options]
$ flow-scripts stub
Generates naive stubs for the packages that your project requires. To be used with flowignore-ing of node_modules for faster start up times.
If you are:
- You are thoroughly annoyed by your web app project taking so long to start up because of Flow and want to
flowignorethenode_modulesfolder - You do not want to check in community libdefs into your repository
- You are okay with not having Flow libdefs for external libraries.
It also possible to combine usage of flow-typed install with flow-scripts stub as stubs for existing libdefs found in flow-typed/npm/ will not be generated.
By default, running Flow on start up will read all the files under node_modules. This takes very very long and it is a huge pain to be waiting that long each time your web app starts. According to Facebook, ignoring the node_modules directory isn't a good idea because Flow looks in there to a) ensure you've actually installed your dependencies and b) find Flow libdefs for packages which might have included them, and Flow will throw a Required module not found error. Refer to this issue for an in-depth discussion on the topic.
However, combined with the inclusion of libdefs (or stubs) for external libraries, ignoring node_modules might not seem like that bad an idea after all.
The workaround is to flowignore the node_modules directory and include the libdefs inside the flow-typed/ directory or provide a stub for it. This can be done manually or automatically via the flow-typed install command.
The flow-typed install command does fetch community libdefs and generates stubs pretty well, but has a few problems:
- Some users might not want to fetch community libdefs because it adds many files to the source.
- The libdefs of some libraries are not pulled into
flow-typed/npm/, such asimmutablebecause it is already present innode_modules/immutable. This is not picked up because weflowignorethenode_modules.
The flow-scripts stub command fixes some of these problems by generating the stubs required for the dependencies in package.json. If there are existing libdef files in the flow-typed/npm directory, the stubs for these libraries will not be generated.
In .flowconfig, add:
[ignore]
.*node_modules/.*
In the project directory, run:
$ flow-scripts stub
This will do the following:
- Tell Flow to ignore checking of
node_modules. - Generates the stubs required for the
dependenciesinpackage.jsonthat are not present inflow-typed/npm/and write them intoflow-typed/package-dep-libdefs.js.
Optional: By adding the script to an npm script postinstall hook, when new packages are installed, it will be automatically added into flow-typed/. It would be recommended to save flow-scripts as a devDependency rather than a global dependency in this case.
In package.json, add this postinstall hook:
"scripts": {
"postinstall": "flow-scripts stub"
},
- A very barebones stub of the library is being generated based solely on the package name. If you are using
lodashand want to import a specific function likelodash/omit, it will not work as the stub generated byflow-scripts stubis forlodashand notlodash/omit. In that case, you might want to pull in a community libdef from flow-typed instead.
- Pull out Flow libdefs for packages that already contain them such as
immutable.
$ flow-scripts unmonitored [options] [pattern]
Searches for files matching the specified glob pattern and lists the files that do not contain @flow. Files that have @noflow are ignored. If pattern is not specified, it defaults to ./**/*.{js,jsx}. Please note that this commands works on files only, and not directories, hence you will have to explicitly specify a file extension. You will also have to quote your parameter (use double quotes if you need it to run in Windows). An example as follows:
$ flow-scripts unmonitored "src/**/*.js"
--fix: Automatically fix those files by adding// @flowat the top.
Testing this library is tricky because it relies on a real project that has multiple dependencies in package.json. Hence we create a mock project in the fixtures folder that has some common JS dependencies defined and symlink the flow-scripts library within that project to our development file in the root folder. Run the commands within that mock project to test that the library is actually working as intended.
$ cd test-project
$ npm install # or yarn install
$ npm link ../
$ flow-scripts stub # flow-typed/package-dep-libdefs.js file should be generated