Repository files navigation

A tool that makes use of theNix package manager to installNode.js dependencies declared inpackage.json andyarn.lock files. It is an experimental project to discover opportunities to use Nix for Node.js dependencies. Read more about the background problemshere.

• Provide incrementalnode_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 ofpackage.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 anode_modules folder or can be placed, or picked up by Nix as a part ofNODE_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 inPATH, with no additional effort.

Let's create a filepackage.nix of a Nix expression with the following content:

withimport<nixpkgs>{};letjs2nix=callPackage(builtins.fetchGit{url="ssh://git@github.com/canva-public/js2nix.git";ref="main";}){};env=js2nix{package-json=./package.json;yarn-lock=./yarn.lock;};inenv.nodeModules

And then anode_modules folder can be created via:

 nix-build --max-jobs auto --out-link ./node_modules ./package.nix

ThenodeModules is a Nix derivation that contains a compatible withNode.js module resolution algorithm layout. Note that the layout of the resultingnode_modules is similar to whatPNPM package manager is providing, that is not aflat 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 thedocumentation space.