Skip to content

docs(start): clarify verbatimModuleSyntax must be disabled #7806

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
galaxykhh wants to merge 3 commits into
base: main
Choose a base branch
from
+13 −5
Open

docs(start): clarify verbatimModuleSyntax must be disabled #7806

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
459f2de
docs(start): clarify verbatimModuleSyntax must be disabled
galaxykhh Jul 13, 2026
3162d78
docs(start): fix verbatimModuleSyntax note wording per review feedback
galaxykhh Jul 14, 2026
2b71eb7
Merge branch 'main' into docs/verbatim-module-syntax-ts6
galaxykhh Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions docs/start/framework/react/build-from-scratch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,16 @@ We highly recommend using TypeScript with TanStack Start. Create a `tsconfig.jso
"module": "ESNext",
"target": "ES2022",
"skipLibCheck": true,
"strictNullChecks": true
"strictNullChecks": true,
"verbatimModuleSyntax": false
}
}
```

> [!NOTE]
> Enabling `verbatimModuleSyntax` can result in server bundles leaking into client bundles. It is recommended to keep this option disabled.
> Enabling `verbatimModuleSyntax` can result in server-only code leaking into client bundles when types are imported from modules that also contain server-only code. It is recommended to keep this option disabled.
>
> TypeScript's compiler default is still `false`, but `tsc --init` (TypeScript 5.9+ and 6.0) generates `"verbatimModuleSyntax": true` as a recommended option. If you use `tsc --init`, explicitly set `"verbatimModuleSyntax": false` in your `tsconfig.json`.

## Install Dependencies

Expand Down
7 changes: 5 additions & 2 deletions docs/start/framework/solid/build-from-scratch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,16 @@ We highly recommend using TypeScript with TanStack Start. Create a `tsconfig.jso
"module": "ESNext",
"target": "ES2022",
"skipLibCheck": true,
"strictNullChecks": true
"strictNullChecks": true,
"verbatimModuleSyntax": false
}
}
```

> [!NOTE]
> Enabling `verbatimModuleSyntax` can result in server bundles leaking into client bundles. It is recommended to keep this option disabled.
> Enabling `verbatimModuleSyntax` can result in server-only code leaking into client bundles when types are imported from modules that also contain server-only code. It is recommended to keep this option disabled.

@coderabbitai coderabbitai Bot Jul 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

sed -n '35,60p' docs/start/framework/solid/build-from-scratch.md && printf '\n---\n' && python3 - <<'PY'
import urllib.request
url='https://www.typescriptlang.org/tsconfig/verbatimModuleSyntax.html'
print(urllib.request.urlopen(url, timeout=20).read().decode('utf-8')[:5000])
PY

Repository: TanStack/router

Length of output: 3773

🏁 Script executed:

python3 - <<'PY'
from pathlib import Path
p=Path('docs/start/framework/solid/build-from-scratch.md')
print(p.exists(), p)
PY

Repository: TanStack/router

Length of output: 207

🏁 Script executed:

sed -n '44,52p' docs/start/framework/solid/build-from-scratch.md

Repository: TanStack/router

Length of output: 669

🌐 Web query:

TypeScript verbatimModuleSyntax import type inline type specifiers erased regular imports server-only code

💡 Result:

The verbatimModuleSyntax compiler option in TypeScript (introduced in 5.0) mandates that TypeScript performs no automatic elision (removal) of import or export statements [1][2]. By default, TypeScript heuristically determines which imports are types and removes them during compilation [3][4]. When verbatimModuleSyntax is enabled, TypeScript emits import and export statements exactly as written in the source code [2][5]. Key implications include: 1. Explicit Syntax Requirements: Developers must explicitly use the type modifier for type-only imports and exports (e.g., import type { T } from 'mod' or import { type T } from 'mod') [2][4]. If an import is not marked as type, TypeScript assumes it is a value import and will include it in the emitted JavaScript, regardless of whether it is used only as a type in your TypeScript code [2][5]. 2. Handling Inline Type Specifiers: An important nuance is that when you use inline type specifiers—such as import { type A } from 'mod'—verbatimModuleSyntax ensures the type part is erased, but the import statement itself remains in the emitted code [6]. If an import declaration contains no value imports and only inline type specifiers, the resulting JavaScript will still contain an empty import (e.g., import {} from 'mod'), which effectively functions as a side-effect import [6][7]. 3. Server-Only Code and Runtime Safety: Because verbatimModuleSyntax preserves imports that are not explicitly marked as type-only, it prevents unintentional runtime errors where TypeScript might have otherwise elided an import that was actually needed at runtime [2][5]. Conversely, it can cause issues in environments like Next.js where importing from a server-only module into a client component is strictly prohibited [7]. If you import a type from a server-only file using an import declaration that contains side effects (or is not strictly a type-only import), the build tool may incorrectly flag the file as a client-side dependency, leading to errors [7]. 4. Compatibility with Node.js Type Stripping: As of 2026, verbatimModuleSyntax is recommended when working with modern Node.js environments that support native "type stripping" (or erasable syntax), as it enforces the explicit syntax required for Node.js to safely strip types without breaking runtime code execution [8][9][10].

Citations:

🌐 Web query:

site:typescriptlang.org verbatimModuleSyntax inline type specifiers import {} from module emitted code

💡 Result:

When the verbatimModuleSyntax compiler option is enabled in TypeScript, the compiler adopts a strict policy regarding imports and exports: it does not transform or elide any import or export statements unless they are explicitly marked with the type modifier [1][2]. For imports and exports containing inline type specifiers, the behavior is as follows: 1. Type-only imports and exports: Any import or export statement that exclusively uses the type modifier (e.g., import type { A } from "a") is erased entirely from the emitted JavaScript code [1]. 2. Mixed imports and exports: If an import or export statement contains both value references and type-only references, the statement is rewritten to remove only the type-only parts [1]. 3. Imports and exports that become empty: If an import or export statement consists entirely of type specifiers (or becomes empty after removing those marked with type), the resulting import or export will be emitted as an empty declaration, such as import {} from "xyz" [1]. This behavior ensures that the emitted code remains consistent with the module format specified by your configuration, preventing TypeScript from implicitly rewriting or eliding code in ways that might conflict with your target module system [1][3].

Citations:

🌐 Web query:

TypeScript verbatimModuleSyntax "import { type" emitted import {} from module

💡 Result:

The verbatimModuleSyntax compiler option in TypeScript (introduced in version 5.0) mandates that all import and export statements are emitted exactly as written, with no automatic elision [1][2][3]. Under this setting, TypeScript stops trying to guess whether an import is used as a value or just a type, and instead relies strictly on whether you use the type modifier [2][4]. Regarding the behavior with import { type... } and empty imports: 1. Import Transformation: When you use the type modifier on named imports, TypeScript removes only the type-specific parts during compilation [2]. 2. Emitted Empty Braces: If an import statement consists entirely of type-only named imports, such as import { type T } from "module", TypeScript will rewrite it to import {} from "module" in the emitted JavaScript [5][2]. 3. Why this happens: This behavior is a direct consequence of the verbatim principle—preserving the original module syntax as much as possible [5]. Because the statement was an import declaration, the output retains the import structure even if the named imports are empty, which effectively becomes a side-effect-only import [5][2]. This approach ensures consistency and forces developers to be explicit about their intentions regarding module usage and side effects, rather than having the compiler silently elide code [2][4]. Because it is more predictable and easier to explain, it replaces the older and more complex flags importsNotUsedAsValues and preserveValueImports [6][2].

Citations:

Clarify that only import type is elided. This warning can read as if any type import is safe, but import { type ... } still emits an import statement. Rephrase it to say the issue is using regular imports for type-only dependencies from server-only modules.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/start/framework/solid/build-from-scratch.md` at line 48, Revise the
`verbatimModuleSyntax` warning to clarify that only `import type` statements are
elided; inline type-only imports such as `import { type ... }` still emit an
import statement. State that regular imports used for type-only dependencies
from server-only modules can leak server code into client bundles, while keeping
the recommendation to disable the option.

>
> TypeScript's compiler default is still `false`, but `tsc --init` (TypeScript 5.9+ and 6.0) generates `"verbatimModuleSyntax": true` as a recommended option. If you use `tsc --init`, explicitly set `"verbatimModuleSyntax": false` in your `tsconfig.json`.

## Install Dependencies

Expand Down
1 change: 1 addition & 0 deletions examples/react/start-counter/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
"isolatedModules": true,
"resolveJsonModule": true,
"skipLibCheck": true,
"verbatimModuleSyntax": false,
"target": "ES2022",
"allowJs": true,
"forceConsistentCasingInFileNames": true,
Expand Down
1 change: 1 addition & 0 deletions examples/solid/start-counter/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
"isolatedModules": true,
"resolveJsonModule": true,
"skipLibCheck": true,
"verbatimModuleSyntax": false,
"target": "ES2022",
"allowJs": true,
"forceConsistentCasingInFileNames": true,
Expand Down
2 changes: 1 addition & 1 deletion packages/start-client-core/skills/start-core/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ plugins: [tanstackStart(), react()]

### 2. HIGH: Enabling verbatimModuleSyntax in tsconfig

`verbatimModuleSyntax` causes server bundles to leak into client bundles. Keep it disabled.
`verbatimModuleSyntax` causes server bundles to leak into client bundles. Keep it disabled. TypeScript's compiler default is still `false`, but `tsc --init` (TypeScript 5.9+ and 6.0) generates `"verbatimModuleSyntax": true` — explicitly set `"verbatimModuleSyntax": false` in `tsconfig.json`.

### 3. HIGH: Missing Scripts component in root route

Expand Down