npmlock2nix

Simple and unit tested solution to nixify npm based packages.

About

npmlock2nix is a Nix based library that parses the package.json and package-lock.json files in order to provide different outputs:

1. A shell environment
2. A node_modules derivation
3. A custom build derivation

Features

• No auto-generated code ✔️
• Works in restricted evaluation ✔️
• GitHub dependencies ✔️
• Unit Tests ✔️
• Integration Tests ✔️

Getting Started

Since npmlock2nix is written entirely in Nix, there aren't any additional prerequisites, it just needs to be imported into your project.

Installation

The preferred way to provide npmlock2nix to your project is via niv:

$ niv add nix-community/npmlock2nix

Assuming you are also tracking nixpkgs via niv, you can then provide npmlock2nix to your project as a nixpkgs overlay

# nix/default.nix
let
  sources = import ./sources.nix;
in
  import sources.nixpkgs {
    overlays = [
      (self: super: {
        npmlock2nix = pkgs.callPackage sources.npmlock2nix { };
      })
    ];
  }

Assuming the setup above, you can import nix/default.nix which will yield a nixpkgs set containing npmlock2nix.

Usage

The following sections outline the main use-case scenarios of npmlock2nix.

Note: All examples only reflect the most basic scenarios and mandatory arguments. For more details please refer to the API documentation.

Note: All code snippets provided below assume that npmlock2nix has been imported and is inn scope and that there are valid package.json and package-lock.json files in the project root.

Providing A Shell

npmlock2nix.shell {
  src = ./.;
}

The shell function creates an environment with the node_modules installed that can be used for development purposes.

Please refer to the API documentation for additional information on shell.

Building node_modules

npmlock2nix.node_modules {
  src = ./.;
}

The node_modules function creates a derivation containing the equivalent of running npm install in an impure environment.

Please refer to the API documentation for additional information on node_modules.

Building A Project

npmlock2nix.build {
  src = ./.;
  installPhase = "cp -r dist $out";
  buildCommands = [ "npm run build" ];
}

The build function can be used to package arbitrary npm based projects. In order for this to work, npmlock2nix must be told how to build the project (buildCommands) and how to install it (installPhase).

Please refer to the API documentation for additional information on build.

Contributing

Contributions to this project are welcome in the form of GitHub Issues or PRs. Please consider the following before creating PRs:

• This project uses nixpkgs-fmt for formatting the Nix code. You can use nix-shell --run "nixpkgs-fmt ." to format everything.
• If you are planning to make any considerable changes, you should first present your plans in a GitHub issue so it can be discussed
• npmlock2nix is developed with a strong emphasis on testing. Please consider providing tests along with your contributions and don't hesitate to ask for support.

Development

When working on npmlock2nix it's highly recommended to use direnv and the project's shell.nix which provides:

• A commit hook for code formatting via nix-pre-commit-hooks.
• A test-runner script that watches the source tree and runs the unit tests on changes.

The integration tests can be executed via nix-build -A tests.integration-tests.

License

Distributed under the Apache 2.0 License. See license for more details

Acknowledgements

• nixpkgs-fmt
• direnv
• niv
• nix-pre-commit-hooks
• entr
• smoke