Document missing pnpmfile hooks

[Silic0nS0ldier]

Adds documentation for;

• filterLog
• fetchers
• importPackage
• preResolution

Local/global pnpmfiles and how they interact is now also documented. For example readPackage is supported by local and global pnpmfiles, and both run with global going first so (global then local).

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

@Silic0nS0ldier is attempting to deploy a commit to the pnpm Team on Vercel.

A member of the Team first needs to authorize it.

[zkochan]

I am not sure we want people to know about these. All these hooks except filterLog were added for easier integration with stackblitz. Would anyone else want to use these low level hooks?

[Silic0nS0ldier]

Would anyone else want to use these low level hooks?

The use case I have in mind sourcing package data directly from the npm_package rule (Bazel ruleset), such that content is identical across Bazel builds and external tools that use pnpm's node_modules (including IDEs).

There are alternatives.

1. Using Bazel's node_modules instance instead, a crude implementation of which exists here, however.
   • This breaks the pnpm patch workflow which relies on pnpm's node_modules existing.
     Related: pnpm patch <name> requires node_modules/.modules.yaml to be present pnpm#8257
   • pnpm is able to do in-place mutation of node_modules which is faster than than copying over.
     Symlinking would close this gap though (why didn't I think to do that before...)
2. Write generated sources into version control (what we are doing at Canva right now).
   • Prevents in-place modification of files. This pattern is unusual in the NodeJS ecosystem, but in the context of our build system such transforms are useful it allows input sources to be normalised (stripping comments, etc) to avoid unnecessary rebuilds, however.
   • Packages in pnpm's node_modules include more files than intended (e.g. .ts sources).
   • Need to confirm generated sources are up-to-date on CI.
   • Devs need to run an extra step whenever such packages are modified (a common complaint, especially when testing changes to a workflow like ESLint which operates outside of our build system).
   • More noise to sift through in code review (even with Github hiding the diff of these generated files).
3. Redirect workspace:* references to tarballs/directories built by Bazel (e.g. by mutating the lockfile). This alternative came about from ideation and has not been implemented. The cons of this haven't had much thought at this stage, off the top of my head it could affect dependency resolution (workspace packages are already by default something of a special case unless they are injected).

The use case I give likely runs into the same dependency resolution issue as mentioned in (3). The issue is not insurmountable (a great deal of flexibility is afforded across all the hooks) but would need to be carefully thought out.

[Silic0nS0ldier]

@zkochan I noticed pnpm v10.10 allows preResolution, importPackage and fetchers hooks in the local .pnpmfile.cjs. Has their scope (stackblitz integration) expanded?

[zkochan]

A few other companies are planning to use the hooks. I added short docs about them: 4e852ad

also, it is now easier to ship hooks via dependencies, using configDependencies.