From 41d8cf69e510f9ef3ca6ea724cfe786c0abd844d Mon Sep 17 00:00:00 2001
From: Ross Smyth <18294397+RossSmyth@users.noreply.github.com>
Date: Wed, 4 Feb 2026 17:21:33 -0500
Subject: [PATCH 1/5] doc: Add documentation on npmHooks.npmBuildHook

---
 doc/hooks/index.md                            |  1 +
 doc/hooks/npm-build-hook.section.md           | 84 +++++++++++++++++++
 .../javascript.section.md                     |  4 +-
 doc/redirects.json                            | 33 ++++++++
 4 files changed, 120 insertions(+), 2 deletions(-)
 create mode 100644 doc/hooks/npm-build-hook.section.md

diff --git a/doc/hooks/index.md b/doc/hooks/index.md
index cd769cec0373..e08766352032 100644
--- a/doc/hooks/index.md
+++ b/doc/hooks/index.md
@@ -27,6 +27,7 @@ libxml2.section.md
 meson.section.md
 mpi-check-hook.section.md
 ninja.section.md
+npm-build-hook.section.md
 patch-rc-path-hooks.section.md
 perl.section.md
 pkg-config.section.md
diff --git a/doc/hooks/npm-build-hook.section.md b/doc/hooks/npm-build-hook.section.md
new file mode 100644
index 000000000000..d044b3118870
--- /dev/null
+++ b/doc/hooks/npm-build-hook.section.md
@@ -0,0 +1,84 @@
+# 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,
+  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
+    npmHooks.npmConfigHook
+    npmHooks.npmBuildHook
+    npmHooks.npmInstallHook
+  ];
+
+  npmBuildScript = "build";
+
+  npmBuildFlags = [
+    "--prod"
+  ];
+
+  npmFlags = [
+    "--ignore-scripts"
+  ];
+
+  npmDeps = fetchNpmDeps {
+    inherit (finalAttrs) src;
+    hash = "...";
+  };
+
+  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)
diff --git a/doc/languages-frameworks/javascript.section.md b/doc/languages-frameworks/javascript.section.md
index 3af4d1d86099..d6ee39da6c33 100644
--- 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`.
diff --git a/doc/redirects.json b/doc/redirects.json
index 05275eb771a0..e23ebc0ad514 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -125,6 +125,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"
   ],
@@ -200,6 +206,33 @@
   "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"
+  ],
   "pkgs-replacevars": [
     "index.html#pkgs-replacevars",
     "index.html#pkgs-substituteall",

From 987a91a6273c4bbf0d5277961a9c5c1b0b43975b Mon Sep 17 00:00:00 2001
From: Ross Smyth <18294397+RossSmyth@users.noreply.github.com>
Date: Wed, 4 Feb 2026 17:41:36 -0500
Subject: [PATCH 2/5] doc: Add npmHooks.npmConfigHook to reference

---
 doc/hooks/index.md                   |  1 +
 doc/hooks/npm-config-hook.section.md | 41 ++++++++++++++++++++++++++++
 doc/redirects.json                   | 27 ++++++++++++++++++
 3 files changed, 69 insertions(+)
 create mode 100644 doc/hooks/npm-config-hook.section.md

diff --git a/doc/hooks/index.md b/doc/hooks/index.md
index e08766352032..6a16b4e65170 100644
--- a/doc/hooks/index.md
+++ b/doc/hooks/index.md
@@ -28,6 +28,7 @@ meson.section.md
 mpi-check-hook.section.md
 ninja.section.md
 npm-build-hook.section.md
+npm-config-hook.section.md
 patch-rc-path-hooks.section.md
 perl.section.md
 pkg-config.section.md
diff --git a/doc/hooks/npm-config-hook.section.md b/doc/hooks/npm-config-hook.section.md
new file mode 100644
index 000000000000..0b1298457605
--- /dev/null
+++ 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`
diff --git a/doc/redirects.json b/doc/redirects.json
index e23ebc0ad514..16aea31242aa 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -233,6 +233,33 @@
   "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"
+  ],
   "pkgs-replacevars": [
     "index.html#pkgs-replacevars",
     "index.html#pkgs-substituteall",

From d76f3f174182070c077da090dc96c65f6f19e7d2 Mon Sep 17 00:00:00 2001
From: Ross Smyth <18294397+RossSmyth@users.noreply.github.com>
Date: Wed, 4 Feb 2026 17:59:23 -0500
Subject: [PATCH 3/5] doc: Document npmHooks.npmInstallHook

---
 doc/hooks/index.md                    |  1 +
 doc/hooks/npm-install-hook.section.md | 35 +++++++++++++++++++++++++++
 doc/redirects.json                    | 24 ++++++++++++++++++
 3 files changed, 60 insertions(+)
 create mode 100644 doc/hooks/npm-install-hook.section.md

diff --git a/doc/hooks/index.md b/doc/hooks/index.md
index 6a16b4e65170..2cd155ccf173 100644
--- a/doc/hooks/index.md
+++ b/doc/hooks/index.md
@@ -29,6 +29,7 @@ mpi-check-hook.section.md
 ninja.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
diff --git a/doc/hooks/npm-install-hook.section.md b/doc/hooks/npm-install-hook.section.md
new file mode 100644
index 000000000000..f099aec13b4a
--- /dev/null
+++ 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)
diff --git a/doc/redirects.json b/doc/redirects.json
index 16aea31242aa..498b60182b6b 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -260,6 +260,30 @@
   "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",

From 471dfbe96cd2be7279821c33918daf3a5aebcc61 Mon Sep 17 00:00:00 2001
From: Ross Smyth <18294397+RossSmyth@users.noreply.github.com>
Date: Wed, 4 Feb 2026 18:19:31 -0500
Subject: [PATCH 4/5] doc: Add documentation on nodejsInstallExecutables

---
 doc/hooks/index.md                            |  1 +
 .../nodejs-install-executables.section.md     | 29 +++++++++++++++++++
 doc/hooks/npm-build-hook.section.md           |  9 +++++-
 doc/redirects.json                            | 15 ++++++++++
 4 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 doc/hooks/nodejs-install-executables.section.md

diff --git a/doc/hooks/index.md b/doc/hooks/index.md
index 2cd155ccf173..d0b039217a35 100644
--- a/doc/hooks/index.md
+++ b/doc/hooks/index.md
@@ -27,6 +27,7 @@ libxml2.section.md
 meson.section.md
 mpi-check-hook.section.md
 ninja.section.md
+nodejs-install-executables.section.md
 npm-build-hook.section.md
 npm-config-hook.section.md
 npm-install-hook.section.md
diff --git a/doc/hooks/nodejs-install-executables.section.md b/doc/hooks/nodejs-install-executables.section.md
new file mode 100644
index 000000000000..7cf1f9ef20e6
--- /dev/null
+++ 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[@]}")
+  '';
+  #...
+})
+```
diff --git a/doc/hooks/npm-build-hook.section.md b/doc/hooks/npm-build-hook.section.md
index d044b3118870..9e09af3589be 100644
--- a/doc/hooks/npm-build-hook.section.md
+++ b/doc/hooks/npm-build-hook.section.md
@@ -14,6 +14,7 @@ Hook for building packages that use npm. Can be used in multi-language environme
   fetchFromGitHub,
   fetchNpmDeps,
   npmHooks,
+  nodejsInstallExecutables,
   nodejs,
 }:
 stdenv.mkDerivation (finalAttrs: {
@@ -31,6 +32,7 @@ stdenv.mkDerivation (finalAttrs: {
 
   nativeBuildInputs = [
     nodejs
+    nodejsInstallExecutables
     npmHooks.npmConfigHook
     npmHooks.npmBuildHook
     npmHooks.npmInstallHook
@@ -51,11 +53,16 @@ stdenv.mkDerivation (finalAttrs: {
     hash = "...";
   };
 
+  makeWrapperArgs = [
+    "--set"
+    "NODE_ENV"
+    "production"
+  ];
+
   meta = {
     description = "npm project";
   };
 })
-
 ```
 :::
 
diff --git a/doc/redirects.json b/doc/redirects.json
index 498b60182b6b..d69908cb6bad 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -203,6 +203,21 @@
   "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"
+  ],
   "nostrictaliasing": [
     "index.html#nostrictaliasing"
   ],

From 240a7b8804c8a9ec1d33fe596fb9dc6e3e4901d5 Mon Sep 17 00:00:00 2001
From: Ross Smyth <18294397+RossSmyth@users.noreply.github.com>
Date: Wed, 4 Feb 2026 18:25:08 -0500
Subject: [PATCH 5/5] doc: Document nodejsInstallManuals

---
 doc/hooks/index.md                          |  1 +
 doc/hooks/nodejs-install-manuals.section.md | 12 ++++++++++++
 doc/hooks/npm-build-hook.section.md         |  2 ++
 doc/redirects.json                          |  6 ++++++
 4 files changed, 21 insertions(+)
 create mode 100644 doc/hooks/nodejs-install-manuals.section.md

diff --git a/doc/hooks/index.md b/doc/hooks/index.md
index d0b039217a35..4ad60b22d1f3 100644
--- a/doc/hooks/index.md
+++ b/doc/hooks/index.md
@@ -28,6 +28,7 @@ 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
diff --git a/doc/hooks/nodejs-install-manuals.section.md b/doc/hooks/nodejs-install-manuals.section.md
new file mode 100644
index 000000000000..454769e32b96
--- /dev/null
+++ 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)
diff --git a/doc/hooks/npm-build-hook.section.md b/doc/hooks/npm-build-hook.section.md
index 9e09af3589be..a3cda18b4449 100644
--- a/doc/hooks/npm-build-hook.section.md
+++ b/doc/hooks/npm-build-hook.section.md
@@ -15,6 +15,7 @@ Hook for building packages that use npm. Can be used in multi-language environme
   fetchNpmDeps,
   npmHooks,
   nodejsInstallExecutables,
+  nodejsInstallManuals,
   nodejs,
 }:
 stdenv.mkDerivation (finalAttrs: {
@@ -33,6 +34,7 @@ stdenv.mkDerivation (finalAttrs: {
   nativeBuildInputs = [
     nodejs
     nodejsInstallExecutables
+    nodejsInstallManuals
     npmHooks.npmConfigHook
     npmHooks.npmBuildHook
     npmHooks.npmInstallHook
diff --git a/doc/redirects.json b/doc/redirects.json
index d69908cb6bad..e9ea2e18f637 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -218,6 +218,12 @@
   "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"
   ],