How to get pnpm to interact nicely with tsc/vue-tsc without turning on shamefullyHoist?

[kleinfreund]

Moving a project from npm to pnpm, I'm now dealing with the rite of passage that is learning whether I can do without shamefullyHoist: true.

The gist is that tsc (specifically vue-tsc but the problem isn't related to vue-tsc specifics) now started to throw hands with a couple of errors like this:

node_modules/transitive-dep/module.js:3:20 - error TS2307: Cannot find module 'transitive-dep'

and setting shamefullyHoist: true is one way to address the issue albeit an unsatisfying one (another unsatisfying option being adding transitive dependencies as direct dependencies). What other options do I have and am I declaring my dependencies correctly?

• Setting publicHoistPattern: ["transitive-dep"] to hoist only problematic transitive dependencies into the root node_modules/ where tsc readily finds them
• Setting nodeLinker: hoisted to create a node_modules/ structure like npm that tsc readily understands

Setup

Host project

Let's start with a minimal host project definition that only lists direct-dep as a direct dependency and nothing else.

host-project/package.json:

{
  "scripts": {
    "type-check": "npx vue-tsc --build"
  },
  "dependencies": {
    "direct-dep": "*"
  }
}

This host project would have some code that uses direct-dep and which would be subject to the vue-tsc type-checking script.

host-project/main.js:

import { directFn } from 'direct-dep/module.js'

directFn()

direct-dep

The direct-dep package in turn only lists transitive-dep as a direct dependency and distributes module.js.

direct-dep/package.json:

{
  "files": ["module.js"],
  "dependencies": {
    "transitive-dep": "1.2.3"
  }
}

The module.js file uses transitive-dep and exports a function of its own to be used by the host project:

direct-dep/module.js:

import { fn } from 'transitive-dep'

export function directFn() {
  fn()
}

Note in particular, that direct-dep does not bundle or inline its dependencies. The module.js file is distributed as-is.

Dependencies

As far as I understand, that is the correct way to declare the dependencies involved. Specifically, host-project shouldn't have transitive-dep as a direct dependency itself because it doesn't directly use it or have another dependency that itself requires it as a peer dependency.

But then how come tsc isn't able to resolve the transitive-dep package?

• After pnpm install, node_modules/direct-dep/node_modules/transitive-dep doesn't exist. I kind of expected that directory to exist and I'm assuming tsc would be able to find the dependency there.
• The root node_modules doesn't have transitive-dep because shamefullyHoist is off. That's expected.
• node_modules/.pnpm/transitive-dep@1.2.3/node_modules/transitive-dep exists, but nothing seems to actually use it (as in there's seemingly no symbolic link inside node_modules/direct-dep that would allow for it to be discovered via links.

The last point in particular is strange: Shouldn't transitive-dep bei available specifically from within node_modules/direct-dep?

I should also say that this exact setup doesn't cause any problems with vite's development server, vitest node-based testing, playwright browser-based testing or ESLint; it's only tsc that doesn't manage to resolve the module. Still, I'm unsure what to do about it short of, well, turning shamefullyHoist on.

[sunnypatell]

@kleinfreund the issue is that vue-tsc uses TypeScript's standard module resolution, which doesn't understand pnpm's .pnpm symlink structure. vite/vitest have their own enhanced resolution that follows these symlinks. tsc doesn't.

the targeted fix is public-hoist-pattern in .npmrc for just the problematic transitive deps:

public-hoist-pattern[]=@problematic/transitive-dep
public-hoist-pattern[]=@types/whatever-is-missing

this hoists only those specific packages to the root node_modules/ where tsc can find them. it's a scalpel vs shamefullyHoist's sledgehammer.

alternatively, just add the missing transitive deps as explicit devDependencies. if tsc needs to resolve them for type-checking, they arguably should be direct deps anyway.

one important note from the pnpm typescript docs: do NOT set "preserveSymlinks": true in tsconfig, it makes things worse with pnpm's layout.

if neither of those work, node-linker=hoisted in .npmrc gives you a flat node_modules (like npm) while keeping pnpm's speed and disk efficiency. it's the official compatibility mode.

this is a well-known class of issues: pnpm#5355, #7810.

[kleinfreund]

Thank you. In the environment I encountered this, I opted to stick to the broad shamefullyHoist approach to reduce long-term friction for other developers. For a smaller set of repositories or personal work, I would likely use publicHoistPattern instead.

alternatively, just add the missing transitive deps as explicit devDependencies. if tsc needs to resolve them for type-checking, they arguably should be direct deps anyway.

That raises an important question for me: is tsc right in not resolving those symlinks as pnpm creates them by default? If so, it would indicate that those transitive dependencies should indeed become direct dependencies. However, I'm not convinced that that's the semantically correct course of action.

In my case, the projects I migrated to pnpm depend directly on a component library that distributes its code as source code directly. So there's no bundling of dependencies, etc. This source code has import statements for a small number of transitive dependencies. Those are being installed as expected, but tsc, as we know, isn't able to discover them within the component library's node_modules.

At the same time, I believe how I modeled the project's dependencies is correct: I only depend on packages that the project uses directly or via peer dependencies and leave the declaration of transitive dependencies to the projects where they're used and so on. If it would be necessary to include such transitive dependencies as direct dependencies instead, then it would mean pnpm's default dependency hierarchy is broken and a flat structure like npm's is required. I don't think that's correct either.

So then what is it? Is tsc wrong and simply unable to handle what I consider to be a valid dependency hierarchy as created by pnpm by default? Or is the hierarchy pnpm creates incorrect/insufficient to allow tsc to properly resolve transitive dependencies? Or is my dependency modeling incorrect after all (which I in turn would read to mean that pnpm's default hierarchy is inappropriate)?

---

References:

• There seem to be a couple of relevant issues in the TypeScript project related to this: https://github.com/microsoft/TypeScript/issues?q=is%3Aissue%20state%3Aopen%20tsc%20not%20resolving%20transitive%20dependencies%20with%20pnpm

[sunnypatell]

@kleinfreund great question. the honest answer is it's a gap between two correct-but-incompatible designs.

tsc follows node's require.resolve algorithm, which resolves symlinks to real paths and walks up node_modules from there. this predates pnpm's strict hierarchy. pnpm's layout is correct per its own model: transitive deps exist in .pnpm but aren't exposed to consumers unless declared.

the problem is that tsc's resolution was designed for flat node_modules. it resolves the symlink to .pnpm/<pkg>/node_modules/<pkg>/, then searches upward from that real path, where the transitive deps aren't visible. vite/vitest have their own enhanced resolution that follows the symlink chain differently.

TypeScript knows about this. microsoft/TypeScript#25376 is the open tracking issue for native package manager awareness, and pnpm is explicitly named. but there's no fix yet.

your dependency modeling is fine. distributing source code with imports into transitive deps is the specific pattern that exposes this gap most painfully, because tsc type-checks those imports at the consumer's resolution scope. for bundled libraries (where imports are already resolved at build time), this never surfaces.

so: not a tsc bug, not a pnpm bug, but a compatibility gap that the TypeScript team acknowledges and hasn't bridged yet. public-hoist-pattern for the specific offending deps is the cleanest workaround until they do.

[sunnypatell]

fwiw the TypeScript#25376 thread has been getting more activity lately so there might be movement on native pnpm-aware resolution eventually. until then your shamefullyHoist call makes sense for distributed source code deps specifically. if this thread covers what you needed, marking it as answered would be nice since this tsc+pnpm gap trips up a lot of people.

[kleinfreund]

Yes, thank you very much for your detailed answers. That helps me understand what problem I'm looking at exactly.

I do think microsoft/TypeScript#25376 is more related to mono repo setups and less so to pnpm/yarn node_modules structures related to the problem described here. In my case, I'm not dealing with a mono repo at all. That being said, it could well be that the same solutions that would allow TypeScript/tsc to understand mono repos better are also what would allow tsc to resolve import paths in isolated node_modules structures.

As an aside, and this is almost fully off topic, thinking about this also made me realize that libraries bundling dependencies shouldn't declare those dependencies in pkg.dependencies but pkg.devDependencies as any consuming project won't ever need to resolve their import paths in their own node_modules. I think I had a big misconception about this for a long time. Unfortunately, there seemingly isn't one correct definition for how one is to correctly model dependencies in package manifests as it's always down to the respective package manager and runtime combination how it actually behaves. I'm not even aware of a central enough piece of documentation that explains when to use dependencies, devDependencies, peerDependencies, etc. with regards to how you distribute your package and whether you bundle or not.