npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

flow-scripts

v0.4.0

Published

Utility scripts for Flowtypes

Downloads

199

Readme

Flow Scripts

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.

Installation

$ npm install -g flow-scripts
$ flow-scripts <command> [options]

Available Commands

Stub

$ flow-scripts stub

What it does

Generates naive stubs for the packages that your project requires. To be used with flowignore-ing of node_modules for faster start up times.

When should you use this?

If you are:

  1. You are thoroughly annoyed by your web app project taking so long to start up because of Flow and want to flowignore the node_modules folder
  2. You do not want to check in community libdefs into your repository
  3. 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.

Motivation

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.

Workaround

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:

  1. Some users might not want to fetch community libdefs because it adds many files to the source.
  2. The libdefs of some libraries are not pulled into flow-typed/npm/, such as immutable because it is already present in node_modules/immutable. This is not picked up because we flowignore the node_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:

  1. Tell Flow to ignore checking of node_modules.
  2. Generates the stubs required for the dependencies in package.json that are not present in flow-typed/npm/ and write them into flow-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"
},

Known Issues

  • A very barebones stub of the library is being generated based solely on the package name. If you are using lodash and want to import a specific function like lodash/omit, it will not work as the stub generated by flow-scripts stub is for lodash and not lodash/omit. In that case, you might want to pull in a community libdef from flow-typed instead.

TODO

  • Pull out Flow libdefs for packages that already contain them such as immutable.

Unmonitored

$ flow-scripts unmonitored [options] [pattern]

What it does

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"

Options

  • --fix: Automatically fix those files by adding // @flow at the top.

Development

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