I want to enable verbatimModuleSyntax. What do I need to beware of?

[aaditmshah]

The docs say:

Enabling verbatimModuleSyntax can result in server bundles leaking into client bundles. It is recommended to keep this option disabled.

The way I understand it is:

// client.ts
import { type User } from "./server";

Will be compiled to:

// client.js
import {} from "./server";

Hence, the server code has been leaked into the client bundle.

However, if I write the following:

// client.ts
import type { User } from "./server";

It will be compiled to:

// client.js
// No import from "./server"

So, as long as I always use import type instead of import { type X } I should be able to use verbatimModuleSyntax?

[ignaciobockl]

Hi @aaditmshah ! Your understanding is essentially correct, with one important nuance.

With verbatimModuleSyntax enabled, TypeScript preserves what you write:

import type { User } from "./server" → fully erased, no runtime import.
import { type User } from "./server" → emitted as import {} from "./server" — preserved as a live empty import, so the module is still evaluated.
Source: TypeScript tsconfig / verbatimModuleSyntax — “any imports or exports without a type modifier are left around, anything that uses the type modifier is dropped entirely.” https://www.typescriptlang.org/tsconfig/verbatimModuleSyntax.html

That is why the TanStack Start note exists:

“Enabling verbatimModuleSyntax can result in server bundles leaking into client bundles. It is recommended to keep this option disabled.”

Source: TanStack/router docs/start/framework/react/build-from-scratch.md, tanstack.com/start docs, and start-core SKILL.md (“HIGH: Enabling verbatimModuleSyntax… Keep it disabled”).

TanStack Start Import Protection confirms the same rule:

“Type-only imports and re-exports are ignored… because they are erased… Mixed imports still count when they include at least one runtime value.”

Source: https://tanstack.com/start/latest/docs/framework/react/guide/import-protection

So yes: if every type-only import is written as import type / export type, that statement cannot leak. The risk is everything around it:

One forgotten import { type X } leaves a live import {} that executes ./server on the client.
Mixed barrels (export { safe } + export { db.server } from same entry) expose a server edge even if the client only uses the safe export. Split entry points.
Re-exports: export { MyType } vs export type { MyType } matter. Same for export { type X } inside a value export.
Codegen / third-party: route-tree, server-fn rewrites, and node_modules (excluded from checks by default) don’t follow your discipline. In dev, import protection can also report false positives before tree-shaking; build-time violations are definitive.
Start compiler pruning: when a createServerFn().handler() is replaced by an RPC stub, unused server imports are pruned — but only if nothing else keeps them alive (see “Common Pitfall: Why Some Imports Stay Alive” in the Import Protection guide).

Recommendation:
Safe default: keep verbatimModuleSyntax disabled, as docs recommend.
If you enable it, only with guardrails:
verbatimModuleSyntax: true + isolatedModules: true
ESLint @typescript-eslint/consistent-type-imports as error with separate type imports, plus consistent-type-exports
importProtection.behavior: { dev: 'error', build: 'error' }, add client.files/specifiers for DB/crypto (/db/, @prisma/client, etc.), use .server/.client naming + server-only/client-only markers
No mixed barrels, audit export type
Verify with production build + client bundle analysis for server strings, and prove the guardrail works by introducing one intentional violation and confirming the build fails.
In short: import type everywhere makes it technically safe, import { type } does not. At scale the safe choice is disabled unless those checks run in CI.

[Navesz]

import type never leaked in anything I tested. But "use import type instead of import { type X }" is not the whole rule. With verbatimModuleSyntax: true, a value import that you only use in a type position still leaks, for example import { getAuth } from './auth' used only as ReturnType<typeof getAuth>. tsc doesn't report it, and the Start/Router compilers don't always remove it. Whether import { type X } leaks also depends on whether one of those compilers rewrote the importing file.

I checked this with a real build instead of reasoning about the transforms. I made a small Start app where every "server" module has a top-level side effect containing a unique string. Each module is imported through exactly one import form. I ran vite build with the option off and on, then searched dist/client for the strings.

Versions: @tanstack/react-start 1.168.53 (start-plugin-core 1.171.43, router-plugin 1.168.38, router-utils 1.162.3), vite 8.3.0 (rolldown 1.2.8), @vitejs/plugin-react 6.1.1, typescript 6.0.3 and 7.0.2, typescript-eslint 8.70.0, Node 24.13.0. The app's package.json has no sideEffects field (see the note below).

Is the server module in dist/client?

importing file	import form	false	true
plain component (not a route, no createServerFn)	import type { T }	no	no
	import { type T }	no	yes
	import { fn }, used only in type X = ReturnType<typeof fn>	no	yes
route file (src/routes/index.tsx)	import type { T }	no	no
	import { type T }	no	no
	import { fn }, used only in a non-exported type X = ReturnType<typeof fn>	no	yes
file with createServerFn	import type { T } / import { type T }	no	no
	import { fn, type T }, fn used only inside .handler()	no	no
	import { fn }, used only in export type X = ReturnType<typeof fn>	no	no
	import { fn }, used only in a non-exported type X = ReturnType<typeof fn>	no	yes

In the leaking builds the side effect ends up as top-level code in client chunks. The route-file one lands in the chunk that the Start manifest loads as the root <script type="module">.

Why it depends on the file

• Files no TanStack compiler rewrites. In my runs, Vite 8 honoured the tsconfig setting for these files. In the dev server's client transform of the plain component, with the option on, you get import "/src/server/leak-p-i.ts"; from import { type T } and import { getThing as pY } from "/src/server/leak-p-y.ts"; from the typeof-only import. With the option off, both are gone.
• Route files and createServerFn files. The Router code-splitter (compilers.ts L837) and the Start compiler (compiler.ts L1412) both call deadCodeElimination from @tanstack/router-utils. The Start compiler only runs on files matching KindDetectionPatterns. Before DCE, stripTypeExports removes import type, inline type specifiers and exported type declarations. It deliberately keeps non-exported type aliases (L98). So type X = ReturnType<typeof fn> still references fn, and the import survives. With the option on, it is emitted as a real import.
• The older mechanism from Server only packages leaking into client bundle via tanstack query #3401 (the compiler turning import { value, type T } into a leftover import { type T }) did not reproduce. The mixed import in the createServerFn file stayed out of the client build.

TypeScript won't flag it

With verbatimModuleSyntax: true, tsc --noEmit passes on this fixture with both 6.0.3 and 7.0.2, because typeof fn is a legal use of a value import. It does raise TS1484 for import { T } of a type, so only that case is enforced.

What caught it

1. Lint. On the fixture, these two rules reported every at-risk import:

   '@typescript-eslint/consistent-type-imports': 'error',     // typeof-only value imports -> `import type { fn }`
   '@typescript-eslint/no-import-type-side-effects': 'error', // `import { type T }` -> `import type { T }`

   The first flagged the 4 typeof-only imports and the second flagged the 3 inline-type imports. After eslint --fix (which produces import type { getThing }), tsc with the option on still passed, and the verbatimModuleSyntax: true build had no server strings in dist/client.
2. Import protection. I renamed the server modules to *.server.ts, which matches the default client deny pattern. The true build then failed with Import denied in client environment ... src/routes/index.tsx:9:29, and the false build passed. In my run it reported only one of the four leaking imports, so it tells you something is wrong but doesn't list every case.

A note on "sideEffects": false

The start-basic / start-bare examples have "sideEffects": false in package.json. When I added that field, the production build dropped every leaked module in all four true cases above. So a project based on those examples may look fine after enabling the option. With that field set, the dev server's client transforms still contain the same imports (import "/src/server/leak-p-i.ts", import { getThing as pY } ..., and so on), so the difference only disappears in the production bundle.

Limits

This is one React fixture on Vite (not rsbuild). I checked production builds and dev-server transforms (via transformRequest), but did not load the page in a browser. I only tested server modules that have top-level side effects. A module without side effects can be tree-shaken even when it is imported, so it may not show up in the bundle. I did not test export { type X } from, barrels/re-exports, or an exported typeof alias in a route file.

Practical takeaway

The docs' "keep it disabled" is still the simpler default. If you want it on, use import type for types and for values used only in typeof, enforce both rules above as errors, and keep a check in CI that searches dist/client for a string that only exists in a server module.