Npm-offline-mirror NPM

npm-offline-mirror

Fast, safe, reproducible builds using NPM.

What

Download package tarballs for inclusion in source control and update package-lock.json to point to them.

How

Find all dependencies in package-lock.json that resolve to a registry URL starting with https: (or http:).
Download the exact same .tgz files that npm install downloads, honoring all configured (.npmrc) registries and registry credentials.
Decompress the .tgz files into .tar files.
Save the .tar files into the project's .npm-offline-mirror directory (configurable).
Rewrite package-lock.json to point at the saved .tar files.

Why

Restore packages faster and without network (eg. when running npm ci --offline in a CI/CD pipeline).
Perfectly replicate builds at any point in source control history.
Protect against supply chain attacks like the left-pad incident.
Improve awareness of shipped dependencies.
Parity with Yarn which has this functionality built-in.

When

Run the npm-offline-mirror command in your project root every time a dependency is modified.

npx npm-offline-mirror

There is currently no way to automatically trigger this command when dependencies change, because NPM does not expose any scripts or other hooks which would allow a command to be run. As an alternative, a pre-commit Git hook could be used to ensure the command is run on every commit.

Requirements

NodeJS >= 16.12
NPM >= 7

Alternatives

Yarn has built-in support for offline mirroring. However Yarn v1 is buggy, and v2 uses PnP which I am not a fan of.

The shrinkpack package was the original implementation of this pattern for NPM. There were even plans once (2018) to integrate it into NPM. However, it has the following limitations.