docs: document finder functions

Author: zkochan

blog/releases/10.16.md

@@ -99,7 +99,7 @@ Every matched package will also print out the license from its `package.json`:
   license: MIT
 ```
 
-### Patch Changes
+## Patch Changes
 
 - Fix deprecation warning printed when executing pnpm with Node.js 24 [#9529](https://github.com/pnpm/pnpm/issues/9529).
 - Throw an error if `nodeVersion` is not set to an exact semver version [#9934](https://github.com/pnpm/pnpm/issues/9934).

docs/cli/list.md

@@ -68,3 +68,7 @@ Exclude peer dependencies from the results (but dependencies of peer dependencie
 ### --filter <package_selector\>
 
 [Read more about filtering.](../filtering.md)
+
+import FindBy from '../settings/_findBy.mdx'
+
+<FindBy />

docs/cli/why.md

@@ -59,3 +59,7 @@ Exclude peer dependencies from the results (but dependencies of peer dependencie
 ### --filter <package_selector\>
 
 [Read more about filtering.](../filtering.md)
+
+import FindBy from '../settings/_findBy.mdx'
+
+<FindBy />

docs/finders.md

@@ -0,0 +1,97 @@
+---
+id: finders
+title: Finders
+---
+
+Added in: v10.16.0
+
+Finder functions let you **search your dependency graph** by any property of a package, not just its name.
+They can be declared in [.pnpmfile.cjs] and used with [pnpm list] and [pnpm why].
+
+[.pnpmfile.cjs]: ./pnpmfile.md
+[pnpm list]: ./cli/list.md
+[pnpm why]: ./cli/why.md
+
+## Defining finder functions
+
+Finder functions are declared in your project’s [.pnpmfile.cjs] file under the finders export.
+Each function receives a context object and must return either:
+
+* `true` → include this dependency in the results,
+* `false` → skip it,
+* or a `string` → include this dependency and print the string as additional info.
+
+Example: a finder that matches any dependency with **React 17** in `peerDependencies`:
+
+```js title=".pnpmfile.cjs"
+module.exports = {
+  finders: {
+    react17: (ctx) => {
+      return ctx.readManifest().peerDependencies?.react === "^17.0.0"
+    }
+  }
+}
+```
+
+### Finder context (ctx)
+
+Each finder function receives a context object that describes the dependency node being visited.
+
+|Field|Type/Example|Description|
+|--|--|--|
+|`name`|`"minimist"`|Package name.|
+|`version`|`"1.2.8"`|Package version.|
+|`readManifest()`|returns the `package.json` object|Load the package manifest (use this for fields like `peerDependencies`, `license`, `engines`, etc.).|
+
+## Using finders
+
+You can invoke a finder with the `--find-by=<functionName>` flag:
+
+```
+pnpm why --find-by=react17
+```
+
+Output:
+
+```
+@apollo/client 4.0.4
+├── @graphql-typed-document-node/core 3.2.0
+└── graphql-tag 2.12.6
+```
+
+## Returning extra metadata
+
+A finder can also return a string. That string will be shown alongside the matched package in the output.
+
+Example: print the package license:
+
+```js
+module.exports = {
+  finders: {
+    react17: (ctx) => {
+      const manifest = ctx.readManifest()
+      if (manifest.peerDependencies?.react === "^17.0.0") {
+        return `license: ${manifest.license}`
+      }
+      return false
+    }
+  }
+}
+```
+
+Output:
+
+```
+@apollo/client 4.0.4
+├── @graphql-typed-document-node/core 3.2.0
+│   license: MIT
+└── graphql-tag 2.12.6
+    license: MIT
+```
+
+Othere example use cases:
+* Find all packages with a specific license.
+* Detect packages requiring a minimum Node.js version.
+* List all dependencies that expose binaries.
+* Print funding URLs for all packages.
+

docs/pnpmfile.md

@@ -174,6 +174,34 @@ This hook allows to override the fetchers that are used for different types of d
 * `directory`
 * `git`
 
+## Finders
+
+Added in: v10.16.0
+
+Finder functions are used with `pnpm list` and `pnpm why` via the `--find-by` flag.
+
+Example:
+
+```js title=".pnpmfile.cjs"
+module.exports = {
+  finders: {
+    react17: (ctx) => {
+      return ctx.readManifest().peerDependencies?.react === "^17.0.0"
+    }
+  }
+}
+```
+
+Usage:
+
+```
+pnpm why --find-by=react17
+```
+
+See [Finders] for more details.
+
+[Finders]: ./finders.md
+
 ## Related Configuration
 
 import IgnorePnpmfile from './settings/_ignorePnpmfile.mdx'

docs/settings/_findBy.mdx

@@ -0,0 +1,7 @@
+### --find-by <finder_name\>
+
+Added in: v10.16.0
+
+Use a [finder function] defined in `.pnpmfile.cjs` to match dependencies by properties other than name.
+
+[finder function]: ../finders.md

sidebars.json

@@ -113,7 +113,8 @@
       "config-dependencies",
       "aliases",
       "completion",
-      "git_branch_lockfiles"
+      "git_branch_lockfiles",
+      "finders"
     ],
     "Recipes": [
       "using-changesets",

versioned_sidebars/version-10.x-sidebars.json

@@ -347,6 +347,10 @@
         {
           "type": "doc",
           "id": "git_branch_lockfiles"
+        },
+        {
+          "type": "doc",
+          "id": "finders"
         }
       ]
     },