type package lookup issue with virtual global store

[s-h-a-d-o-w]

For repro, see this branch here: https://github.com/s-h-a-d-o-w/next-global-store-repro/tree/react-types-problem
After cloning and installing, check out the error in layout.tsx, caused by not finding @types/react.

Claude suggested that next would have to declare the types as a peer dependency: "pnpm then links it into the package's own virtual node_modules"
Which doesn't actually seem to be the case, because other peer dependencies that it declares and that are available (like react) are not linked like that.

And so I'm wondering whether this is really a problem with the next.js dependencies or whether there's a problem with how the virtual global store works. Maybe both?

[KingEmma7]

This looks like an interaction between pnpm's experimental global virtual store and TypeScript's package resolution, rather than proof that @types/react is absent from your app. In your repro package.json, @types/react is a direct dev dependency. The lockfile resolves it to 19.3.0, while the installed Next snapshot declares react and react-dom as peers but not @types/react. That explains the different links you noticed: pnpm links declared peers alongside Next's package, but it has no peer link to add for the React types.

With virtualStoreType: global, your node_modules/next points outside the project into pnpm's shared store. A .d.ts resolved from that real package location does not necessarily see the app's node_modules/@types by walking parent directories. pnpm documents the shared symlink layout and warns that some tools do not work with it (global virtual store guide). There is also an open pnpm issue #14972 describing this exact Next.js 16 / global-store combination, including the separate @types/react resolution failure and a project-store workaround.

I would first set virtualStoreType: project explicitly in pnpm-workspace.yaml, reinstall, and run pnpm exec tsc --noEmit. If that removes the layout.tsx error, it isolates the global-store layout as the trigger. Merely deleting the setting might leave a user-level global setting active. Then compare node_modules/next and node_modules/@types/react targets, and keep the exact TypeScript error text and pnpm/Node versions in the report. I would avoid adding @types/react as a Next peer in your app's package metadata: that is a package-maintainer decision and would not address the other global-store/Turbopack resolution problem recorded in #14972.

So my practical recommendation for this Next app is the project virtual store until the upstream compatibility issues are resolved. I have inspected the repro and related issue, but have not run it locally, so I would use the A/B reinstall above to confirm it on your machine.

Written by an agent (OpenAI Codex, GPT-6).

[s-h-a-d-o-w]

I've seen the warning. It says "a dependency importing a package it does not declare". So if the library declares dependencies, it should be fine.
But... types don't work like runtime imports. You don't declare those as regular dependencies. And it seems like that may not have been considered by the pnpm team yet.

#14972 is primarily about building, the type problem was only mentioned incidentally and hasn't gotten attention yet. I just made a note there about that.

[KingEmma7]

Agreed: the warning about undeclared runtime imports does not tell us whether TypeScript can find a declaration package. I ran your react-types-problem branch at commit a5e0fd4 with its pinned pnpm 11.26.0 and TypeScript 5.9.3 on Node 24.11.1/macOS arm64. With virtualStoreType: global, pnpm exec tsc --noEmit --incremental false fails at app/layout.tsx:28 because ScriptProps lacks type. Repeating with --skipLibCheck false exposes TS7016 in Next's .d.ts files: React resolves to JS in the global store, but its types are not found from that location.

In a second checkout I changed only virtualStoreType to project, reinstalled from the same frozen lockfile, and the normal tsc command passed. With --skipLibCheck false, that checkout still has separate URLPattern declaration errors in this Next canary, but the React TS7016 errors disappeared. This reproduces the type-resolution gap without running Turbopack; your note on pnpm #14972 is supported by this A/B check.

Written by an agent (OpenAI Codex, GPT-6).

[dgesteves]

I ran your repro (pnpm 11.26.0, react-types-problem @ a5e0fd4, TS 5.9.3). Two things are going on:

1. Declared peers are linked next to the package in the global virtual store. Next's link dir (<store>/v11/links/@/next/16.4.0-canary.43/<hash>/node_modules/) contains next, react, react-dom, @next/*, styled-jsx, and so on. @types/react isn't there because Next doesn't declare it.
2. TypeScript resolves imports from the real path of next/dist/*.d.ts. It walks up from inside the store and never reaches your project's node_modules/@types. It finds react as JS with no types (TS7016 with --skipLibCheck false), so React's types never load through Next's declarations and ScriptProps loses type. With the project store this works because your project node_modules is an ancestor of .pnpm/…. With the global store it isn't.

You can keep the global store and give Next the peers it's missing:

# pnpm-workspace.yaml
packageExtensions:
  next:
    peerDependencies:
      '@types/react': '*'
      '@types/react-dom': '*'
    peerDependenciesMeta:
      '@types/react':
        optional: true
      '@types/react-dom':
        optional: true

Run pnpm install and commit the lockfile; Next's snapshot key now includes the @types/* peers. Results on your repro:

	tsc --noEmit	TS7016 react / react-dom (--skipLibCheck false)
global store, as-is	fails at app/layout.tsx:28	62 / 9
+ @types/react	passes	0 / 9
+ @types/react and @types/react-dom	passes	0 / 0

The 7 errors left with --skipLibCheck false are this canary's URLPattern declarations, which are unrelated.

I'd call this a gap in the global virtual store rather than in Next. Any package whose .d.ts imports a module whose types live in a separate @types/* package needs that @types package as a sibling. That's the point you added on #14972. Until pnpm handles it, add the same extension for any other library that hits it, or use virtualStoreType: project for this app. Mapping react to ./node_modules/@types/react with tsconfig paths also makes tsc pass, but it doesn't cover Next's /// <reference types="react/experimental" />, so packageExtensions is the cleaner fix.

_{Written by an agent (Claude Code, claude-opus-5-5), reviewed by me.}

[dgesteves]

@s-h-a-d-o-w following up: I didn't see anything in the release notes since then (up to 12.11.1) that changes how the global virtual store links @types/* packages, so the packageExtensions workaround should still be needed. Did it fix the ScriptProps error on your side? If it did, marking it as the answer would help others who hit this with the global store. If not, I'm happy to dig further.

_{Written by an agent (Claude Code, claude-opus-5-5), reviewed by me.}

[s-h-a-d-o-w]

Odd, I didn't get notified of this despite the @ mention.

Anyway... I generally don't use workarounds. I'm just not using the virtual global store until this is resolved.
While I'm thankful for your help, I will mark the official resolution via new config as the resolution.

[zkochan]

#16810 adds an addMissingPeerTypes setting to pnpm v12. With addMissingPeerTypes: true in pnpm-workspace.yaml, every peer dependency X of a package also makes @types/X an optional peer, unless the package already declares it. Yarn applies the same rule. For this repro, @types/react and @types/react-dom get linked next to next in the global virtual store, as the packageExtensions workaround above does, but for every package that peer-depends on a library.

The setting is off by default, and turning it on re-resolves the lockfile. Until it ships, the packageExtensions workaround is the way to go.

---

Written by an agent (Claude Code, claude-opus-5-5).

[zkochan]

I am not sure about the name of the setting. implicitTypesPeers looks ugly, no?

[s-h-a-d-o-w]

Awesome stuff!
I see you've already been working on the name. Personally, I'm just hoping you'll mention this in the global virtual store docs, since I probably won't remember why this is needed a year from now. 😅

[zkochan]

I think this should be on by default but we can only do that in next major

[s-h-a-d-o-w]

Ah, good to hear and makes sense that you'll do it with the next major.