bug: Server-only modules leak into client bundle with Next.js 16.2.0

[lindit]

Describe the bug

When using create-t3-app (v7.40.0, with tRPC + Drizzle + PostgreSQL) as a starter and upgrading Next.js to 16.2.0, next build fails with 6 "Module not found" errors (fs, net, tls, perf_hooks). Next.js 16.1.7 builds successfully — the regression is specific to 16.2.0.

The root cause is that 16.2.0 follows the module graph for type-only imports in "use client" files, pulling server-only code into the client bundle.

The import chain causing the leak:

src/trpc/react.tsx ("use client")
  → import { type AppRouter } from "~/server/api/root"
    → import { createCallerFactory, createTRPCRouter } from "~/server/api/trpc"
      → import { db } from "~/server/db"
        → import postgres from "postgres"   // ← uses fs, net, tls, perf_hooks

How to reproduce

1. pnpm create t3-app@latest (select tRPC + Drizzle + PostgreSQL)
2. In package.json, change "next" to "16.2.0"
3. Run pnpm install && pnpm build
4. Build fails with:

   Module not found: Can't resolve 'fs'
   Module not found: Can't resolve 'net'
   Module not found: Can't resolve 'tls'
   Module not found: Can't resolve 'perf_hooks'
   

Note: The same project builds successfully with Next.js 16.1.7.

Expected behavior

The build should succeed. Type-only imports (import { type AppRouter }) should not cause the bundler to follow the server module graph from a client component.

Environment

• create-t3-app: v7.40.0
• Next.js: 16.2.0 (breaks) / 16.1.7 (works)
• Node.js: v22
• Package manager: pnpm

Possible solutions

1. Export the AppRouter type from a separate file that doesn't import any server code (e.g., src/server/api/types.ts that re-exports only the type)
2. Add serverExternalPackages: ['postgres'] to next.config.js
3. Add import "server-only" to server files as a guard
4. Some combination of the above

[EricTsai83]

Hit the same issue. The cleanest workaround on the app side is to re-export AppRouter through a type-only barrel file so that "use client" files never directly import from ~/server/.

Create src/trpc/types.ts:

export type { AppRouter } from "~/server/api/root";

Then update the two client-side consumers:

// src/trpc/react.tsx
- import { type AppRouter } from "~/server/api/root";
+ import { type AppRouter } from "./types";

// src/trpc/client.ts  (if you have one)
- import type { AppRouter } from "~/server/api/root";
+ import type { AppRouter } from "./types";

src/trpc/server.ts doesn't need changes since it already has import "server-only".

Why this works

With verbatimModuleSyntax: true (which the T3 template enables), export type { … } from "…" is erased entirely by the TypeScript compiler before the bundler sees it. So types.ts produces zero runtime imports — the bundler never follows the chain into ~/server/api/root → db → postgres.

The key difference from importing directly in react.tsx is that the intermediate file contains nothing but a type re-export, so even if a bundler version incorrectly resolves the module specifier, the resolved module (types.js) is empty and has no further imports to follow.

Longer-term

This is arguably a Next.js 16.2.0 regression — import { type X } should be erased before module resolution. It might be worth opening an issue on next.js as well. But I am not pretty sure.

[Gaen]

An alternative workaround would be the following:

- import { type AppRouter } from "~/server/api/root";
+ import type { AppRouter } from "~/server/api/root";