Expose nodeDependencies in node-env.nix (#199)

* Expose nodeDependencies in node-env.nix

* Add some documentation to the README

* Try to actually expose the nodeDependencies

* Update some files

* Fix the NixAttrReferences

* Fix PackageExpression.js again

Co-authored-by: Tom McLaughlin <[email protected]>

README.md

@@ -26,6 +26,7 @@ Table of Contents
     - [Deploying a Node.js development project](#deploying-a-nodejs-development-project)
     - [Generating a tarball from a Node.js development project](#generating-a-tarball-from-a-nodejs-development-project)
     - [Deploying a development environment of a Node.js development project](#deploying-a-development-environment-of-a-nodejs-development-project)
+    - [Using the Node.js environment in other Nix derivations](#using-the-nodejs-environment-in-other-nix-derivations)
     - [Deploying a collection of NPM packages from the NPM registry](#deploying-a-collection-of-npm-packages-from-the-npm-registry)
     - [Using NPM lock files](#using-npm-lock-files)
     - [Generating packages for specific Node.js versions](#generating-packages-for-specific-nodejs-versions)
@@ -185,6 +186,42 @@ For example, the following command should work:
 $ node bin/node2nix.js --help
 ```
 
+Using the Node.js environment in other Nix derivations
+--------------------------------------------------------------------
+The `node_modules` environment generated by `node2nix` can also be used in
+downstream Nix expressions. This can be useful when you want to build a project
+that requires running a build system such as Webpack in your Node.js environment.
+
+This environment can be found on the `nodeDependencies` attribute of the
+generated output. It contains two important paths: `lib/node_modules` and `bin`.
+The former should be copied or symlinked into your build directory, and the
+latter should be added to the PATH. (You can also use the `NODE_PATH`
+environment variable, but see the warnings about that
+[below](#creating-a-symlink-to-the-node_modules-folder-in-a-shell-session).)
+
+Here's an example derivation showing this technique:
+
+```nix
+let
+  nodeDependencies = (pkgs.callPackage ./my-app {}).nodeDependencies;
+
+in
+
+stdenv.mkDerivation {
+  name = "my-webpack-app";
+  src = ./my-app;
+  buildInputs = [nodejs];
+  buildPhase = ''
+    ln -s ${nodeDependencies}/lib/node_modules ./node_modules
+    export PATH="${nodeDependencies}/bin:$PATH"
+
+    # Build the distribution bundle in "dist"
+    webpack
+    cp -r dist $out/
+  '';
+}
+```
+
 Deploying a collection of NPM packages from the NPM registry
 ------------------------------------------------------------
 The secondary use of `node2nix` is deploying existing NPM packages from the NPM

lib/expressions/PackageExpression.js

@@ -75,6 +75,14 @@ PackageExpression.prototype.toNixAST = function() {
                 refExpr: new nijs.NixExpression("buildNodeShell")
             }),
             paramExpr: new nijs.NixExpression("args")
+        }),
+
+        nodeDependencies: new nijs.NixFunInvocation({
+            funExpr: new nijs.NixAttrReference({
+                attrSetExpr: new nijs.NixExpression("nodeEnv"),
+                refExpr: new nijs.NixExpression("buildNodeDependencies")
+            }),
+            paramExpr: new nijs.NixExpression("args")
         })
     };
 

nix/node-env.nix

@@ -445,8 +445,8 @@ let
       '';
     } // extraArgs);
 
-  # Builds a development shell
-  buildNodeShell =
+  # Builds a node environment (a node_modules folder and a set of binaries)
+  buildNodeDependencies =
     { name
     , packageName
     , version
@@ -465,8 +465,8 @@ let
 
     let
       extraArgs = removeAttrs args [ "name" "dependencies" "buildInputs" ];
-
-      nodeDependencies = stdenv.mkDerivation ({
+    in
+      stdenv.mkDerivation ({
         name = "node-dependencies-${name}-${version}";
 
         buildInputs = [ tarWrapper python nodejs ]
@@ -512,6 +512,27 @@ let
           ln -s $out/lib/node_modules/.bin $out/bin
         '';
       } // extraArgs);
+
+  # Builds a development shell
+  buildNodeShell =
+    { name
+    , packageName
+    , version
+    , src
+    , dependencies ? []
+    , buildInputs ? []
+    , production ? true
+    , npmFlags ? ""
+    , dontNpmInstall ? false
+    , bypassCache ? false
+    , reconstructLock ? false
+    , dontStrip ? true
+    , unpackPhase ? "true"
+    , buildPhase ? "true"
+    , ... }@args:
+
+    let
+      nodeDependencies = buildNodeDependencies args;
     in
     stdenv.mkDerivation {
       name = "node-shell-${name}-${version}";
@@ -538,5 +559,6 @@ in
 {
   buildNodeSourceDist = stdenv.lib.makeOverridable buildNodeSourceDist;
   buildNodePackage = stdenv.lib.makeOverridable buildNodePackage;
+  buildNodeDependencies = stdenv.lib.makeOverridable buildNodeDependencies;
   buildNodeShell = stdenv.lib.makeOverridable buildNodeShell;
 }

tests/grunt/node-packages.nix

@@ -1401,5 +1401,6 @@ in
   sources = sources;
   tarball = nodeEnv.buildNodeSourceDist args;
   package = nodeEnv.buildNodePackage args;
-  shell = nodeEnv.buildNodeShell args;
-}
+  shell = (nodeEnv.buildNodeShell args).shell;
+  nodeDependencies = (nodeEnv.buildNodeShell args).nodeDependencies;
+}

tests/lockfile/node-packages.nix

@@ -746,5 +746,6 @@ in
   sources = sources;
   tarball = nodeEnv.buildNodeSourceDist args;
   package = nodeEnv.buildNodePackage args;
-  shell = nodeEnv.buildNodeShell args;
-}
+  shell = (nodeEnv.buildNodeShell args).shell;
+  nodeDependencies = (nodeEnv.buildNodeShell args).nodeDependencies;
+}

tests/scoped/node-packages.nix

@@ -22,5 +22,6 @@ in
   sources = sources;
   tarball = nodeEnv.buildNodeSourceDist args;
   package = nodeEnv.buildNodePackage args;
-  shell = nodeEnv.buildNodeShell args;
-}
+  shell = (nodeEnv.buildNodeShell args).shell;
+  nodeDependencies = (nodeEnv.buildNodeShell args).nodeDependencies;
+}