doc: Document npmHooks and nodejs hooks (#487075)

2026-06-05 21:03:40 +00:00 · 2026-03-27 19:33:08 +00:00
parent 57bc25d357 240a7b8804
commit 10fc5a6a4b
8 changed files with 322 additions and 2 deletions
--- a/doc/hooks/index.md
+++ b/doc/hooks/index.md
@@ -28,6 +28,11 @@ libxml2.section.md
 meson.section.md
 mpi-check-hook.section.md
 ninja.section.md
+nodejs-install-executables.section.md
+nodejs-install-manuals.section.md
+npm-build-hook.section.md
+npm-config-hook.section.md
+npm-install-hook.section.md
 patch-rc-path-hooks.section.md
 perl.section.md
 pkg-config.section.md
--- a/doc/hooks/nodejs-install-executables.section.md
+++ b/doc/hooks/nodejs-install-executables.section.md
@@ -0,0 +1,29 @@
+# nodejsInstallExecutables {#nodejs-install-executables}
+
+Hook for wrapping Node.js executables.
+Primarily created for a multi-language environment.
+
+## Examples {#nodejs-install-executables-example}
+
+[](#npm-build-hook-example-snippet)
+
+## Variables controlling `nodejsInstallExecutables` {#nodejs-install-executables-variables}
+
+### `nodejsInstallExecutables` Exclusive Variables {#nodejs-install-executables-exclusive-variables}
+
+#### `makeWrapperArgs` {#nodejs-install-executables-wrapper-args}
+
+Flags to pass to the call to [`makeWrapper`](#fun-makeWrapper).
+To avoid double-wrapping, this flag can also be accessed in Bash.
+
+```nix
+stdenv.mkDerivation (finalAttrs: {
+  #...
+  dontWrapGApps = true;
+
+  postInstall = ''
+    makeWrapperArgs+=("''${gappsWrapperArgs[@]}")
+  '';
+  #...
+})
+```
--- a/doc/hooks/nodejs-install-manuals.section.md
+++ b/doc/hooks/nodejs-install-manuals.section.md
@@ -0,0 +1,12 @@
+# nodejsInstallManuals {#nodejs-install-manuals}
+
+Detects manuals in Node.js packages, and attempts to install them in standard locations.
+This detection is done by inspecting the package.json of the project and finding any entries
+with type `man`.
+
+
+There are no ways currently to configure this hook.
+
+## Examples {#nodejs-install-manuals-example}
+
+[](#npm-build-hook-example-snippet)
--- a/doc/hooks/npm-build-hook.section.md
+++ b/doc/hooks/npm-build-hook.section.md
@@ -0,0 +1,93 @@
+# npmHooks.npmBuildHook {#npm-build-hook}
+
+Hook for building packages that use npm. Can be used in multi-language environments.
+
+## Examples {#npm-build-hook-snippet}
+
+:::{.example #npm-build-hook-example-snippet}
+
+# Using `npmHooks`
+
+```nix
+{
+  stdenv,
+  fetchFromGitHub,
+  fetchNpmDeps,
+  npmHooks,
+  nodejsInstallExecutables,
+  nodejsInstallManuals,
+  nodejs,
+}:
+stdenv.mkDerivation (finalAttrs: {
+  pname = "some-npm-project";
+  version = "1.0";
+
+  src = fetchFromGitHub {
+    owner = "JohnNpm";
+    repo = "SomeProject";
+    tag = finalAttrs.version;
+    hash = "...";
+  };
+
+  strictDeps = true;
+
+  nativeBuildInputs = [
+    nodejs
+    nodejsInstallExecutables
+    nodejsInstallManuals
+    npmHooks.npmConfigHook
+    npmHooks.npmBuildHook
+    npmHooks.npmInstallHook
+  ];
+
+  npmBuildScript = "build";
+
+  npmBuildFlags = [
+    "--prod"
+  ];
+
+  npmFlags = [
+    "--ignore-scripts"
+  ];
+
+  npmDeps = fetchNpmDeps {
+    inherit (finalAttrs) src;
+    hash = "...";
+  };
+
+  makeWrapperArgs = [
+    "--set"
+    "NODE_ENV"
+    "production"
+  ];
+
+  meta = {
+    description = "npm project";
+  };
+})
+```
+:::
+
+## Variables controlling `npmBuildHook` {#npm-build-hook-variables}
+
+### `npmBuildHook` Exclusive Variables {#npm-build-hook-exclusive-variables}
+
+#### `npmBuildScript` {#npm-build-hook-script}
+
+Controls the script ran to build the npm package within the `package.json` file.
+Required to be set, usually to `build`, but can vary between packages.
+
+#### `npmBuildFlags` {#npm-build-hook-flags}
+
+Controls the arguments to the {command}`npm run $npmBuildScript` command.
+
+#### `dontNpmBuild` {#npm-build-hook-dont}
+
+Disables `npmBuildHook` when enabled
+
+### Honored Variables {#npm-build-hook-honored-variables}
+
+The following variables are honored by the `npmBuildHook`.
+
+- [`npmWorkspace`](#javascript-buildNpmPackage-npmWorkspace)
+- [`npmFlags`](#javascript-buildNpmPackage-npmFlags)
--- a/doc/hooks/npm-config-hook.section.md
+++ b/doc/hooks/npm-config-hook.section.md
@@ -0,0 +1,41 @@
+# npmHooks.npmConfigHook {#npm-config-hook}
+
+Hook for configuring packages that use npm.
+Primarily made for a multi-language environment.
+
+## Examples {#npm-config-hook-snippet}
+
+[](#npm-build-hook-example-snippet)
+
+## Variables controlling `npmConfigHook` {#npm-config-hook-variables}
+
+### `npmConfigHook` Exclusive Variables {#npm-config-hook-exclusive-variables}
+
+#### `npmDeps` {#npm-config-hook-deps}
+
+Derivation that contains the NPM package dependencies.
+Usually built with `fetchNpmDeps`.
+This attribute is required or the hook will abort the build.
+
+#### `makeCacheWritable` {#npm-config-hook-writable-cache}
+
+Whether to make the dependency cache writable prior to installing the dependencies.
+Don't set this unless npm tries to write to the cache directory.
+
+#### `npmInstallFlags` {#npm-config-hook-install-flags}
+
+Flags to pass to the {command}`npm ci` call for installing the dependencies to the build environment.
+Defaults to `--ignore-scripts`, which cannot be removed.
+This does not control anything with the `npmInstallHook`.
+
+#### `npmRebuildFlags` {#npm-config-hook-rebuild-flags}
+
+Flags to pass to the {command}`npm rebuild` command after the dependencies are installed to the environment.
+
+### Honored Variables {#npm-config-hook-honored-variables}
+
+The following variables are honored by the `npmConfigHook`.
+
+- [`npmWorkspace`](#javascript-buildNpmPackage-npmWorkspace)
+- [`npmFlags`](#javascript-buildNpmPackage-npmFlags)
+- `npmRoot`
--- a/doc/hooks/npm-install-hook.section.md
+++ b/doc/hooks/npm-install-hook.section.md
@@ -0,0 +1,35 @@
+# npmHooks.npmInstallHook {#npm-install-hook}
+
+Hook to install node_modules for npm packages.
+Does not create wrappers for executable npm projects
+Primarily made for a multi-language environment.
+
+## Examples {#npm-install-hook-snippet}
+
+[](#npm-build-hook-example-snippet)
+
+## Variables controlling `npmInstallHook` {#npm-install-hook-variables}
+
+### `npmInstallHook` Exclusive Variables {#npm-install-hook-exclusive-variables}
+
+#### `dontNpmPrune` {#npm-install-hook-dont-prune}
+
+Whether to run {command}`npm prune` on the `node_modules` or not.
+Defaults to `true`.
+
+#### `npmInstallFlags` {#npm-install-hook-prune-flags}
+
+Flags to pass to the {command}`npm prune` call for the `node_modules` of the package.
+Defaults to `--omit=dev --no-save` which cannot be modified.
+
+#### `dontNpmInstall` {#npm-install-hook-dont}
+
+Controls whether `npmInstallHook` is enabled or not.
+Defaults to `true`, so the hook will run.
+
+### Honored Variables {#npm-install-hook-honored-variables}
+
+The following variables are honored by the `npmInstallHook`.
+
+- [`npmWorkspace`](#javascript-buildNpmPackage-npmWorkspace)
+- [`npmFlags`](#javascript-buildNpmPackage-npmFlags)
--- a/doc/languages-frameworks/javascript.section.md
+++ b/doc/languages-frameworks/javascript.section.md
@@ -147,10 +147,10 @@ If these are not defined, `npm pack` may miss some files, and no binaries will b
 * `npmDepsHash`: The output hash of the dependencies for this project. Can be calculated in advance with [`prefetch-npm-deps`](#javascript-buildNpmPackage-prefetch-npm-deps).
 * `makeCacheWritable`: Whether to make the cache writable prior to installing dependencies. Don't set this unless npm tries to write to the cache directory, as it can slow down the build.
 * `npmBuildScript`: The script to run to build the project. Defaults to `"build"`.
-* `npmWorkspace`: The workspace directory within the project to build and install.
+* []{#javascript-buildNpmPackage-npmWorkspace} `npmWorkspace`: The workspace directory within the project to build and install.
 * `dontNpmBuild`: Option to disable running the build script. Set to `true` if the package does not have a build script. Defaults to `false`. Alternatively, setting `buildPhase` explicitly also disables this.
 * `dontNpmInstall`: Option to disable running `npm install`. Defaults to `false`. Alternatively, setting `installPhase` explicitly also disables this.
-* `npmFlags`: Flags to pass to all npm commands.
+* []{#javascript-buildNpmPackage-npmFlags} `npmFlags`: Flags to pass to all npm commands.
 * `npmInstallFlags`: Flags to pass to `npm ci`.
 * `npmBuildFlags`: Flags to pass to `npm run ${npmBuildScript}`.
 * `npmPackFlags`: Flags to pass to `npm pack`.
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -134,6 +134,12 @@
  "inkscape-plugins": [
    "index.html#inkscape-plugins"
  ],
+  "javascript-buildNpmPackage-npmFlags": [
+    "index.html#javascript-buildNpmPackage-npmFlags"
+  ],
+  "javascript-buildNpmPackage-npmWorkspace": [
+    "index.html#javascript-buildNpmPackage-npmWorkspace"
+  ],
  "libcxxhardeningextensive": [
    "index.html#libcxxhardeningextensive"
  ],
@@ -206,9 +212,108 @@
  "no-broken-symlinks.sh": [
    "index.html#no-broken-symlinks.sh"
  ],
+  "nodejs-install-executables": [
+    "index.html#nodejs-install-executables"
+  ],
+  "nodejs-install-executables-example": [
+    "index.html#nodejs-install-executables-example"
+  ],
+  "nodejs-install-executables-exclusive-variables": [
+    "index.html#nodejs-install-executables-exclusive-variables"
+  ],
+  "nodejs-install-executables-variables": [
+    "index.html#nodejs-install-executables-variables"
+  ],
+  "nodejs-install-executables-wrapper-args": [
+    "index.html#nodejs-install-executables-wrapper-args"
+  ],
+  "nodejs-install-manuals": [
+    "index.html#nodejs-install-manuals"
+  ],
+  "nodejs-install-manuals-example": [
+    "index.html#nodejs-install-manuals-example"
+  ],
  "nostrictaliasing": [
    "index.html#nostrictaliasing"
  ],
+  "npm-build-hook": [
+    "index.html#npm-build-hook"
+  ],
+  "npm-build-hook-dont": [
+    "index.html#npm-build-hook-dont"
+  ],
+  "npm-build-hook-example-snippet": [
+    "index.html#npm-build-hook-example-snippet"
+  ],
+  "npm-build-hook-exclusive-variables": [
+    "index.html#npm-build-hook-exclusive-variables"
+  ],
+  "npm-build-hook-flags": [
+    "index.html#npm-build-hook-flags"
+  ],
+  "npm-build-hook-honored-variables": [
+    "index.html#npm-build-hook-honored-variables"
+  ],
+  "npm-build-hook-script": [
+    "index.html#npm-build-hook-script"
+  ],
+  "npm-build-hook-snippet": [
+    "index.html#npm-build-hook-snippet"
+  ],
+  "npm-build-hook-variables": [
+    "index.html#npm-build-hook-variables"
+  ],
+  "npm-config-hook": [
+    "index.html#npm-config-hook"
+  ],
+  "npm-config-hook-deps": [
+    "index.html#npm-config-hook-deps"
+  ],
+  "npm-config-hook-exclusive-variables": [
+    "index.html#npm-config-hook-exclusive-variables"
+  ],
+  "npm-config-hook-honored-variables": [
+    "index.html#npm-config-hook-honored-variables"
+  ],
+  "npm-config-hook-install-flags": [
+    "index.html#npm-config-hook-install-flags"
+  ],
+  "npm-config-hook-rebuild-flags": [
+    "index.html#npm-config-hook-rebuild-flags"
+  ],
+  "npm-config-hook-snippet": [
+    "index.html#npm-config-hook-snippet"
+  ],
+  "npm-config-hook-variables": [
+    "index.html#npm-config-hook-variables"
+  ],
+  "npm-config-hook-writable-cache": [
+    "index.html#npm-config-hook-writable-cache"
+  ],
+  "npm-install-hook": [
+    "index.html#npm-install-hook"
+  ],
+  "npm-install-hook-dont": [
+    "index.html#npm-install-hook-dont"
+  ],
+  "npm-install-hook-dont-prune": [
+    "index.html#npm-install-hook-dont-prune"
+  ],
+  "npm-install-hook-exclusive-variables": [
+    "index.html#npm-install-hook-exclusive-variables"
+  ],
+  "npm-install-hook-honored-variables": [
+    "index.html#npm-install-hook-honored-variables"
+  ],
+  "npm-install-hook-prune-flags": [
+    "index.html#npm-install-hook-prune-flags"
+  ],
+  "npm-install-hook-snippet": [
+    "index.html#npm-install-hook-snippet"
+  ],
+  "npm-install-hook-variables": [
+    "index.html#npm-install-hook-variables"
+  ],
  "pkgs-replacevars": [
    "index.html#pkgs-replacevars",
    "index.html#pkgs-substituteall",