Choosing Between pnpm Default and Strict Mode for Monorepo Dependency Safety

Decision and constraints

Enable pnpm strict mode to enforce that only packages listed in dependencies or devDependencies can be imported, preventing accidental reliance on transitive packages.

Constraints to consider before switching:

• Requires pnpm v6.0 or newer.
• All projects in the workspace must use the same lockfile version (v6+).
• CI pipelines should run pnpm install --frozen-lockfile to avoid lockfile drift.

Options comparison

Mode	Description	Pros	Cons
Default (non‑strict)	Allows any package present in node_modules to be required.	Simple setup; works with legacy packages that rely on implicit transitive imports.	Risk of hidden dependencies; harder to upgrade safely; builds may be nondeterministic.
Strict (enabled via strict-peer-deps)	Enforces that imports match declared dependencies or devDependencies.	Guarantees an explicit dependency graph; safer refactors and more reproducible builds.	May break code that currently uses undeclared transitive imports; requires package.json updates before enabling.

Trade‑offs

Strict mode improves reproducibility and reduces surprise failures caused by hidden dependencies. The downside is an initial refactor cost: any file that imports a package not listed in its manifest will fail to build. Default mode is easier to adopt immediately but can lead to version conflicts and nondeterministic CI results over time.

Implementation and validation

1. Add the strict‑peer‑deps setting to the workspace configuration. You can place it in either .npmrc at the workspace root or in pnpm-workspace.yaml:

   # .npmrc
   strict-peer-deps=true
   

   or

   # pnpm-workspace.yaml
   packages:
     - '**'
   
   npm_config_strict_peer_deps: true
   

   Run this edit with write access to the repository root.

2. Install dependencies with a frozen lockfile to ensure the setting is applied:

   # Run in the workspace root (requires read/write on node_modules)
   pnpm install --frozen-lockfile
   

3. Validate that the mode is active:

   • Check the config: pnpm config get strict-peer-deps should output true.
   • Attempt to import an undeclared package. For example, create a test file packages/pkg-b/test.js that contains:

   // test.js
   const undeclared = require('some-package-not-in-pkg-b');
   console.log(undeclared);
   

   Run pnpm --filter pkg-b run node test.js (or execute the file directly). With strict mode enabled the command should fail with an error similar to:

   Error: Cannot find module 'some-package-not-in-pkg-b'
   

   If the import succeeds, strict mode is not being enforced; verify the config and lockfile version.

4. Optional: detect missing declarations before enabling strict mode:

   # Lists packages that are imported but not declared
   pnpm ls --unused
   

   Review the output and add any missing entries to the relevant package.json files.

Limitations and practical checks

Strict mode only validates peer dependencies when the flag is on; it does not block access to regular transitive dependencies unless those are also listed in dependencies or devDependencies. Therefore, after enabling the mode you should still:

• Run pnpm ls --unused periodically to catch newly introduced undeclared imports.
• Ensure CI runs pnpm install --frozen-lockfile so the lockfile cannot drift and re‑introduce hidden dependencies.

To confirm the setting persists across machines, check the config in any clone:

pnpm config get strict-peer-deps

If the output is false, the mode is not active and you must reapply the configuration.