doc: Add pnpmBuildHook

doc/hooks/index.md

@@ -37,6 +37,7 @@ npm-install-hook.section.md
 patch-rc-path-hooks.section.md
 perl.section.md
 pkg-config.section.md
+pnpm.section.md
 postgresql-test-hook.section.md
 premake.section.md
 python.section.md

doc/hooks/pnpm.section.md

@@ -0,0 +1,142 @@
+# pnpmBuildHook {#pnpm-build-hook}
+
+[pnpm](https://pnpm.io/) is a an NPM-compatible package manager focused on increasing managment speeds, and reducing disk space.
+
+The `pnpmBuildHook` in Nixpkgs overrides the default build phase for building packages that use pnpm.
+
+:::{.example #ex-pnpm-build-hook}
+## pnpmBuildHook example code snippet {#pnpm-build-hook-code-snippet}
+
+```
+{
+  lib,
+  stdenv,
+  fetchFromGitHub,
+  fetchPnpmDeps,
+  pnpmConfigHook,
+  pnpmBuildHook,
+  makeBinaryWrapper,
+  pnpm_10,
+}:
+let
+  pnpm = pnpm_10;
+in
+stdenv.mkDerivation (finalAttrs: {
+  pname = "coolPackages";
+  version = "1.0";
+
+  src = fetchFromGitHub {
+    owner = "JaneCool";
+    repo = "coolpackage";
+    tag = finalAttrs.version;
+    hash = lib.fakeHash;
+  };
+
+  __structuredAttrs = true;
+  strictDeps = true;
+
+  pnpmDeps = fetchPnpmDeps {
+    inherit (finalAttrs) pname version src;
+    inherit pnpm;
+    fetcherversion = 4;
+    hash = lib.fakeHash;
+  };
+
+  nativeBuildInputs = [
+    pnpmConfigHook
+    pnpmBuildHook
+    makeBinaryWrapper
+  ];
+
+  pnpmBuildScript = "build";
+  pnpmBuildFlags = [
+    "--mode"
+    "production"
+  ];
+  pnpmWorkspaces = [
+    "test"
+  ];
+
+  installPhase = ''
+    runHook preInstall
+
+    mkdir "$out"
+    cp -r dist/. "$out"
+
+    runHook postInstall
+  '';
+
+  meta = {
+    description = "very cool package that does cool things";
+    mainProgram = "cool";
+  };
+})
+```
+:::
+
+## Variables controlling pnpmBuildHook {#pnpm-build-hook-variables}
+
+### pnpm Exclusive Variables {#pnpm-build-hook-exclusive-variables}
+
+#### `pnpmBuildScript` {#pnpm-build-hook-script}
+
+Controls the script ran to build the package, by default the script is `build`.
+
+#### `pnpmFlags` {#pnpm-build-hook-flags}
+
+Controls flags used for all invocations of pnpm across all hooks local to this derivation.
+
+#### `pnpmBuildFlags` {#pnpm-build-hook-build-flags}
+
+Controls the flags pass only to the pnpm build script invocation.
+
+#### `dontPnpmBuild` {#pnpm-build-hook-dont}
+
+Disables automatically running `pnpmBuildHook`. The build can still be run manually if needed, for example:
+
+```
+{
+  lib,
+  rustPlatform,
+  pnpmBuildHook,
+  pnpmConfigHook,
+  fetchPnpmDeps,
+  emptyDirectory,
+  pnpm_10,
+}:
+let
+  pnpm = pnpm_10;
+in
+rustPlatform.buildRustPackage (finalAttrs: {
+  pname = "super-fast-application";
+  version = "1.0";
+
+  src = emptyDirectory;
+
+  cargoHash = lib.fakeHash;
+
+  nativeBuildInputs = [
+    pnpmBuildHook
+    pnpmConfigHook
+  ];
+
+  pnpmDeps = fetchPnpmDeps {
+    inherit (finalAttrs) pname version src;
+    inherit pnpm;
+    fetcherversion = 3;
+    hash = lib.fakeHash;
+  }
+
+  dontPnpmBuild = true;
+  postBuild = ''
+    pnpmBuildHook
+  '';
+})
+```
+
+### Honored Variables {#pnpm-build-hook-honored-variables}
+
+The following variables are honored by `pnpmBuildHook`.
+
+* [`pnpmRoot`](#javascript-pnpm-sourceRoot)
+* [`pnpmWorkspaces`](#javascript-pnpm-workspaces)

doc/languages-frameworks/javascript.section.md

@@ -309,6 +309,8 @@ pnpm is available as the top-level package `pnpm`. Additionally, there are varia
 
 When packaging an application that includes a `pnpm-lock.yaml`, you need to fetch the pnpm store for that project using a fixed-output-derivation. The function `fetchPnpmDeps` can create this pnpm store derivation. In conjunction, the setup hook `pnpmConfigHook` will prepare the build environment to install the pre-fetched dependencies store. Here is an example for a package that contains `package.json` and a `pnpm-lock.yaml` files using the fetcher and setup hook above:
 
+There is also the [`pnpmBuildHook`](#pnpm-build-hook) for building packages with `pnpm`, as seen in [](#ex-pnpm-build-hook).
+
 ```nix
 {
   fetchPnpmDeps,

doc/redirects.json

@@ -113,6 +113,9 @@
   "ex-pkgs-replace-vars-with": [
     "index.html#ex-pkgs-replace-vars-with"
   ],
+  "ex-pnpm-build-hook": [
+    "index.html#ex-pnpm-build-hook"
+  ],
   "ex-shfmt": [
     "index.html#ex-shfmt"
   ],
@@ -346,6 +349,33 @@
   "pkgs.treefmt.withConfig": [
     "index.html#pkgs.treefmt.withConfig"
   ],
+  "pnpm-build-hook": [
+    "index.html#pnpm-build-hook"
+  ],
+  "pnpm-build-hook-build-flags": [
+    "index.html#pnpm-build-hook-build-flags"
+  ],
+  "pnpm-build-hook-code-snippet": [
+    "index.html#pnpm-build-hook-code-snippet"
+  ],
+  "pnpm-build-hook-dont": [
+    "index.html#pnpm-build-hook-dont"
+  ],
+  "pnpm-build-hook-exclusive-variables": [
+    "index.html#pnpm-build-hook-exclusive-variables"
+  ],
+  "pnpm-build-hook-flags": [
+    "index.html#pnpm-build-hook-flags"
+  ],
+  "pnpm-build-hook-script": [
+    "index.html#pnpm-build-hook-script"
+  ],
+  "pnpm-build-hook-variables": [
+    "index.html#pnpm-build-hook-variables"
+  ],
+  "pnpm-build-hook-honored-variables": [
+    "index.html#pnpm-build-hook-honored-variables"
+  ],
   "preface": [
     "index.html#preface"
   ],