A tool that makes use of the Nix package manager to install Node.js dependencies declared in package.json
and yarn.lock
files. It is an experimental project to discover opportunities to use Nix for Node.js dependencies. Read more about the background problems here.
- Provide incremental
node_modules
installations (don't build what have already been built) by turning every individual npm package into a self-containing Nix derivation - Handle dependency cycles
- Allow overriding a package
- Allow package life-cycle scripts and their overrides
- Make the dependency graph explicit (expressed in Nix) and well-controlled with all the above
- Remove the need to be check generated files into a code-base, provides IFD if required
- Make the generation of the Nix expression pure, so no assumptions are made around missing SHAs, local packages locations, etc
It is implemented as a CLI tool written in JavaScript and as a Nix library that picks up that tool and executes it internally to generate a Nix expression out of the given tuple of package.json
& yarn.lock
files in a pure manner as a separate Nix derivation, that then can be imported into the Nix runtime and the generated Nix derivations will be built via the provided Nix library to install Node.js dependencies.
Then the artifact can be symlinked to some local location as a node_modules
folder or can be placed, or picked up by Nix as a part of NODE_PATH
to make it available for the Node.js resolution mechanism. Also, every derivation that represents an npm package is a first-class citizen in Nix and can be used independently, which is a convenient way to provide Node.js based CLIs in Nix. That is, if the npm package exposes a binary, it will be picked up by Nix and being made available in PATH
, with no additional effort.
Let's create a file package.nix
of a Nix expression with the following content:
with import <nixpkgs> { };
let
js2nix = callPackage (builtins.fetchGit {
url = "ssh://git@github.com/canva-public/js2nix.git";
ref = "main";
}) { };
env = js2nix {
package-json = ./package.json;
yarn-lock = ./yarn.lock;
};
in env.nodeModules
And then a node_modules
folder can be created via:
nix-build --max-jobs auto --out-link ./node_modules ./package.nix
The nodeModules
is a Nix derivation that contains a compatible with Node.js module resolution algorithm layout. Note that the layout of the resulting node_modules
is similar to what PNPM
package manager is providing, that is not a flat layout but rather the canonical layout with symlinked (from the Nix store) npm packages into it.
To find out more about the project, its background, implementation details, how to use it please go to the documentation space.