npm package npm package Stats

Apply npm best practices, including package.json, maintaining dependencies, security, release automation and monorepos.

package.json
npm scripts
Dependencies
Publishing

package.json

1. Consider adding scope to package names

You can publish multiple related npm packages under one scope: @scope/package-name. Then you get the freedom to name packages, while clarifying which project they belong to.

Resources:

2. Specify package meta information

Define the following fields in package.json:

  • description - a short description indexed by npm search
  • keywords - an array of case-insensitive strings indexed by npm search. Use letters, digits and dashes for better discoverability in search.
  • homepage - project website or repository URL
  • repository - repository URL
  • bugs - issue tracker URL
  • main - path to the main package entry point
Resources:

3. Comments in package.json

package.json being a JSON file doesn't support comments (such as // ...). However, you can use custom fields to save notes without interfering with npm. For example, "comment": "...comment goes here...".

Resources:

npm scripts

1. Running scripts in parallel

  • The best way to run several npm scripts in parallel is to use npm-run-all or concurrently.

  • Don't use cmd1 & cmd2 for that purpose. In Linux it will run cmd1 as a background process, which may not be automatically killed once finished.

Resources:

2. Write cross-platform npm scripts

  • For a cross-platform implementation (Windows/Linux/macOs) of common Unix shell commands use shx.
  • To set environment variables use cross-env.
  • To remove files and directories use rimraf.
  • To write different scripts for each platform use run-script-os.
Resources:

3. Commonly used scripts

Dependencies

1. Dependency pinning vs version ranges

  • For library (require()'d by other packages) dependencies use version ranges, preferably ^. It prevents package duplication in user installations. Feel free to pin exact versions in devDependencies.
  • For apps the best pinning strategy depends on the tools you use to update dependencies. For dependencies choose between exact versions, ~ and ^ depending on how well they follow semantic versioning.
  • Keep in mind that even if you pin all packages in package.json sub-dependencies can only be pinned using a lock file.
Resources:

2. Pay attention to lock files

  • Always commit lock file into repository. It helps all package developers to work with the same versions of dependencies.
  • Dependencies in package.json and lock files don't always stay in sync. This can lead to surprises in how npm install works. For dependencies consistent between two files the version in lock file is used, while inconsistencies are resolved using package.json.
  • For deployment use npm ci or yarn install --frozen-lockfile to ignore package.json while installing packages.
  • Unlike package-lock.json, that are not bundled into npm packages, npm-shrinkwrap.json is preserved and respected by npm install. While it allows to pin the exact versions of sub-dependencies, it also leads to duplicate package installations and stale dependencies. Using npm-shrinkwrap.json is strongly discouraged for libraries, but acceptable for command line tools, daemons and development dependencies.
Resources:

3. Keep dependencies up to date

There are several ways to update dependencies manually:

  • npm update - built-in command, updates respecting semver ranges
  • npm-check - a comprehensive tool for updating and detecting unused dependencies,
  • npm-check-updates - updates dependencies to the latest versions, ignoring semver ranges
  • npm-upgrade - interactive tool with changelogs inspection support

These services can automatically identify packages to update and create pull requests for your repository:

  • Renovate - a flexible service for GitHub and GitLab, supports multiple languages
  • Dependabot - a free service owned by GitHub, supports multiple languages
  • Depfu - works with GitHub and GitLab, supports JavaScript and Ruby
  • Greenkeeper - for GitHub repositories with continuous integration configured
  • David - simply provides a page to monitor the update status of your dependencies

4. Assess the quality of dependencies

  • Visualize npm depedencies graph with NPMGraph.
  • Get a quick dependency assessment with NPM Introspect (see how it works).
  • Is it popular popular? Look at GitHub stars, npm download statistics (via npm trends) and number of dependents.
  • Is it actively developed and maintained? When was it released? When was the last activity (commit, issue, release)? Are reported issues addressed (see opened/closed issue statistics)? Keep in mind, that for simple packages the lack of activity sometimes means maturity rather than abandonment.
  • Is it of high quality? Does it have documentation and changelog? Is it covered by tests? Does the code look well? You can explore package contents using npmfs.
Resources:

5. Keep dependencies slim

6. Audit dependencies for security vulnerabilities

  • Regularly perform built-in npm audit.
  • Setup Snyk to watch repository and notify you about known vulnerabilities.
  • Disable run-scripts when installing new packages using npm install <package> --ignore-scripts. To make this behaviour default run npm config set ignore-scripts true.

7. Review dependency licenses

  • Check whether dependency licenses are compatible with your project.
  • Explore dependency licenses using Legally or NPM License Checker.
  • Review the obligations imposed by these licenses using tldrlegal.
Resources:

Publishing

1. Use .npmignore carefully

Note that if .npmignore is provided then files listed in .gitignore are no longer excluded from npm package. Make sure to blacklist all unnecessary files in .npmignore or whitelist them using files field in package.json.

Resources:

2. Avoid publishing secrets or unnecessary files

  • Exclude sensitive data (such as API keys) and unnecessary development files (such as .nyc_output) from the package using .gitignore or files property of package.json.
  • Also consider excluding examples, documentation and tests (especially if they are large).
  • Before publishing review package contents by running npm publish --dry-run.
Resources:

3. Bower is now deprecated

Bower has not been actively developed since 2016 and it's creator, Adam Stankiewicz, recommends to move aways from it. You can consider dropping Bower support by following the official guide.

Resources:

Apply this and many other checklists to your project