Node.js

Common questions and solutions for using Node.js with Flox

Build with Flox

Not only can you develop your software with Flox, but you can build it as well. See the builds concept page for more details.

Manifest builds

npm

Building Node.js packages with npm looks similar to building for containers or serverless functions. On a high level, builds for Node.js-based projects generally follow this pattern:

[build.myproject]
command = '''
# Install dependencies
npm ci

# Build
npm run build
# -> assuming this yields a `dist` directory

# Install the build result to `out`
mkdir -p $out
mv ./dist $out/

## If your app does not use a bundler
## and needs additional node_modules at runtime,
## `npm prune` and copy the node modules to $out
#
# npm prune --include "prod"
# cp -r ./node_modules $out

# Create a run script
mkdir -p $out/bin
echo "#!/usr/bin/env sh" > $out/bin/myproject
echo 'exec node $out/dist/index.js "$@"' >> $out/bin/myproject
chmod 755 $out/bin/myproject
'''

If you expect to install multiple Node.js applications in the same environment, we recommend putting the dist (and optional node_modules) under an appropriate namespace, e.g. create /libexec/myproject/dist in your build.

For the run script, if your npm build already produces a binary that can be executed directly, you can also copy or link that to $out/bin. Note that only binaries in $out/bin are wrapped to ensure they run within a consistent environment.

Vendoring dependencies in pure builds

As discussed in the pure builds of the Builds concept page, pure builds run in a sandbox without network access on Linux. A pure build can be run as a multi-stage build where the first step vendors dependencies. An example is shown below:

[build.myproject-deps]
command = '''
  mkdir -p $out
  npm ci
  cp -r node_modules $out
'''

[build.myproject]
command = '''
  # Copy node modules built in the previous step
  cp --no-preserve=mode -r ${myproject-deps}/node_modules ./
  ...
  # The rest of the build is the same
'''
sandbox = "pure"

Nix expression builds

To build a project using buildNpmPackage which will import your existing dependency file:

{
  buildNpmPackage,
  importNpmLock,
}:

buildNpmPackage (final: {
  pname = "myproject";
  version = "0.1.0";
  src = ../../../.;

  npmDeps = importNpmLock {
    npmRoot = final.src;
  };
  npmConfigHook = importNpmLock.npmConfigHook;
  npmBuildScript = "build";
});