Home

Awesome

<!-- badges -->

License Contributors Issues PRs Tests Matrix

<!-- teaser --> <br /> <p align="center"> <h2 align="center">npmlock2nix</h2> <p align="center"> Simple and unit tested solution to nixify npm based packages. </p> </p>

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

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:

Development

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

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

<!-- MARKDOWN LINKS & IMAGES --> <!--Other external links -->