doc: Add documentation on npmHooks.npmBuildHook

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

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)

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`.

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",