From 459f2dedc3062f1bfeb2fd3fe5edec47f2353961 Mon Sep 17 00:00:00 2001 From: hyeonghan Date: Mon, 13 Jul 2026 21:59:24 +0900 Subject: [PATCH 1/2] docs(start): clarify verbatimModuleSyntax must be disabled The build-from-scratch guides only said to keep `verbatimModuleSyntax` disabled without showing how, and didn't mention that `tsc --init` (TypeScript 5.9+ and 6.0) now generates `"verbatimModuleSyntax": true`. Add `"verbatimModuleSyntax": false` to the example tsconfig and clarify that the compiler default is still `false` while the init template opts in. Co-authored-by: Cursor --- docs/start/framework/react/build-from-scratch.md | 7 +++++-- docs/start/framework/solid/build-from-scratch.md | 7 +++++-- examples/react/start-counter/tsconfig.json | 1 + examples/solid/start-counter/tsconfig.json | 1 + packages/start-client-core/skills/start-core/SKILL.md | 2 +- 5 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/start/framework/react/build-from-scratch.md b/docs/start/framework/react/build-from-scratch.md index a0a04f06d4..e29d250dfc 100644 --- a/docs/start/framework/react/build-from-scratch.md +++ b/docs/start/framework/react/build-from-scratch.md @@ -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. +> TanStack Start does not support `verbatimModuleSyntax` enabled — it can cause server-only code to leak into client bundles. +> +> 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 diff --git a/docs/start/framework/solid/build-from-scratch.md b/docs/start/framework/solid/build-from-scratch.md index 5343f21e8b..807d2d6160 100644 --- a/docs/start/framework/solid/build-from-scratch.md +++ b/docs/start/framework/solid/build-from-scratch.md @@ -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. +> TanStack Start does not support `verbatimModuleSyntax` enabled — it can cause server-only code to leak into client bundles. +> +> 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 diff --git a/examples/react/start-counter/tsconfig.json b/examples/react/start-counter/tsconfig.json index cef9369516..22ce35b408 100644 --- a/examples/react/start-counter/tsconfig.json +++ b/examples/react/start-counter/tsconfig.json @@ -10,6 +10,7 @@ "isolatedModules": true, "resolveJsonModule": true, "skipLibCheck": true, + "verbatimModuleSyntax": false, "target": "ES2022", "allowJs": true, "forceConsistentCasingInFileNames": true, diff --git a/examples/solid/start-counter/tsconfig.json b/examples/solid/start-counter/tsconfig.json index 508ace2e17..fdee488ec1 100644 --- a/examples/solid/start-counter/tsconfig.json +++ b/examples/solid/start-counter/tsconfig.json @@ -11,6 +11,7 @@ "isolatedModules": true, "resolveJsonModule": true, "skipLibCheck": true, + "verbatimModuleSyntax": false, "target": "ES2022", "allowJs": true, "forceConsistentCasingInFileNames": true, diff --git a/packages/start-client-core/skills/start-core/SKILL.md b/packages/start-client-core/skills/start-core/SKILL.md index 82481417bc..0b2f5fe543 100644 --- a/packages/start-client-core/skills/start-core/SKILL.md +++ b/packages/start-client-core/skills/start-core/SKILL.md @@ -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 From 3162d788a74b38891ff881e6c6ebe5f1281ac01f Mon Sep 17 00:00:00 2001 From: galaxykhh Date: Tue, 14 Jul 2026 17:25:21 +0900 Subject: [PATCH 2/2] docs(start): fix verbatimModuleSyntax note wording per review feedback Clarify that verbatimModuleSyntax can be used but may leak server-only code into client bundles when importing types from mixed modules. Co-authored-by: Cursor --- docs/start/framework/react/build-from-scratch.md | 2 +- docs/start/framework/solid/build-from-scratch.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/start/framework/react/build-from-scratch.md b/docs/start/framework/react/build-from-scratch.md index e29d250dfc..6f099115c1 100644 --- a/docs/start/framework/react/build-from-scratch.md +++ b/docs/start/framework/react/build-from-scratch.md @@ -46,7 +46,7 @@ We highly recommend using TypeScript with TanStack Start. Create a `tsconfig.jso ``` > [!NOTE] -> TanStack Start does not support `verbatimModuleSyntax` enabled — it can cause server-only code to leak into client bundles. +> 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`. diff --git a/docs/start/framework/solid/build-from-scratch.md b/docs/start/framework/solid/build-from-scratch.md index 807d2d6160..7715079661 100644 --- a/docs/start/framework/solid/build-from-scratch.md +++ b/docs/start/framework/solid/build-from-scratch.md @@ -45,7 +45,7 @@ We highly recommend using TypeScript with TanStack Start. Create a `tsconfig.jso ``` > [!NOTE] -> TanStack Start does not support `verbatimModuleSyntax` enabled — it can cause server-only code to leak into client bundles. +> 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`.