Moving a project off shamefully-hoist: which legacy build scripts break under pnpm's strict node_modules layout

Answer to the three core questions

1. Auditing phantom imports: pnpm has no single command that lists every undeclared import. The recommended workflow is a “dry run” branch: remove shamefully-hoist=true, delete node_modules and pnpm-lock.yaml, run pnpm install and then execute the full build‑test‑lint pipeline. Any resolution errors that surface are the real‑world list of phantom dependencies. For a static pre‑flight, run depcheck, knip or eslint‑plugin‑import's no‑extraneous‑dependencies rule; these tools flag imports that are not present in package.json but may produce false positives for dynamic require() calls. 2. Middle‑ground hoisting: pnpm offers hoist-pattern (default: node_modules/.pnpm/node_modules) and public-hoist-pattern. The latter is the direct replacement for shamefully-hoist=true and allows you to hoist only the packages you actually need into the root node_modules. For example:

# .npmrc
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

This keeps the root layout strict while satisfying tools that still expect a flat structure. 3. Tool categories that usually require public‑hoist‑pattern:

• ESLint plugins and configs that are referenced by string name.
• Prettier plugins (e.g., prettier-plugin-foo) loaded via require() in a prettier.config.js.
• Jest transformers, reporters, or environment modules that resolve by string.
• Bundler plugins (Rollup, Webpack) that are loaded by name in a config file.
• TypeScript type packages used only by the compiler (e.g., @types/lodash) when the compiler is run from a script that imports them via require().

In most cases the fix is to declare the package explicitly in package.json (as a devDependency if it’s only needed for tooling). Hoisting should be reserved for the handful of tools that cannot be fixed by a direct import.

Practical steps for your project

1. Branch off the current state and edit .npmrc to remove shamefully-hoist=true.

2. Delete node_modules and pnpm-lock.yaml to force a clean install.

3. Run pnpm install and note any errors that mention “cannot find module …” or “extraneous dependency”.

4. Run the full CI pipeline locally (build, test, lint). Record any failures that occur at runtime or in the test runner.

5. Run a static audit: npx depcheck --skip-unused --skip-dev or npx knip. Compare the list with the runtime failures; any overlap is a candidate for a public-hoist-pattern or a new devDependency.

6. For each tool that still fails after adding the missing devDependencies, add a targeted public-hoist-pattern[] entry as shown above.

7. Commit the changes, delete node_modules again, run pnpm install and verify that the build passes.

What detail might change the recommendation?

If your project uses a lot of require('plugin-name') calls where the plugin name is constructed at runtime, you may need a more permissive public-hoist-pattern or a custom resolver. Please let us know if you have such dynamic loading patterns.