From 391f6535ad109409705185255ad74310706a0ee0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Curley?= Date: Mon, 21 Sep 2026 12:37:18 +0100 Subject: [PATCH 1/5] feat(cli): add interactive router-only prompt Prompt 'Use Tanstack Router without Start?' in interactive mode when router-only intent is not already explicit via --router-only, a legacy template, or --template/--starter. Answering yes sets cliOptions.routerOnly so template, deployment, add-on, and example prompts are skipped. --- packages/cli/src/options.ts | 11 ++++++++++- packages/cli/src/ui-prompts.ts | 12 ++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/packages/cli/src/options.ts b/packages/cli/src/options.ts index f09b55a24..5b12ed2b6 100644 --- a/packages/cli/src/options.ts +++ b/packages/cli/src/options.ts @@ -21,6 +21,7 @@ import { selectGit, selectInstall, selectPackageManager, + selectRouterOnly, selectTemplate, selectToolchain, } from './ui-prompts.js' @@ -95,9 +96,17 @@ export async function promptForCreateOptions( ['file-router', 'typescript', 'tsx', 'javascript', 'js', 'jsx'].includes( template, ) + const hasTemplateIntent = !!cliOptions.template || !!cliOptions.starter const routerOnly = !!cliOptions.routerOnly || - (isLegacyTemplate ? template !== 'file-router' : false) + (isLegacyTemplate ? template !== 'file-router' : false) || + (cliOptions.routerOnly === undefined && + !isLegacyTemplate && + !hasTemplateIntent && + (await selectRouterOnly())) + if (routerOnly) { + cliOptions.routerOnly = true + } if (!cliOptions.starter) { if (cliOptions.template && !isLegacyTemplate) { diff --git a/packages/cli/src/ui-prompts.ts b/packages/cli/src/ui-prompts.ts index 396adba8b..271300695 100644 --- a/packages/cli/src/ui-prompts.ts +++ b/packages/cli/src/ui-prompts.ts @@ -53,6 +53,18 @@ export async function selectFramework( return framework } +export async function selectRouterOnly(): Promise { + const routerOnly = await confirm({ + message: 'Use Tanstack Router without Start?', + initialValue: false, + }) + if (isCancel(routerOnly)) { + cancel('Operation cancelled.') + process.exit(0) + } + return routerOnly +} + export async function selectInstall(): Promise { const install = await confirm({ message: 'Would you like to install dependencies now?', From 18b1dd1eb9971836e56e20d0040bc5e9c19d8911 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Curley?= Date: Mon, 21 Sep 2026 12:45:46 +0100 Subject: [PATCH 2/5] feat(cli): add --router-and-start flag Strict inverse of --router-only: explicitly opts into TanStack Start and suppresses the interactive router-only prompt. Errors when combined with --router-only and ignores legacy router-only templates in favor of Start. --- docs/cli-reference.md | 1 + packages/cli/src/cli.ts | 28 ++++++++++++++++++++++++++++ packages/cli/src/types.ts | 1 + 3 files changed, 30 insertions(+) diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 259ae6298..4d9988cb5 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -19,6 +19,7 @@ tanstack create [project-name] [options] | `--package-manager ` | `npm`, `pnpm`, `yarn`, `bun`, `deno` | | `--framework ` | `React`, `Solid` | | `--router-only` | Create file-based Router-only app without TanStack Start (add-ons/deployment/template disabled) | +| `--router-and-start` | Use TanStack Start explicitly (skips the interactive router-only prompt) | | `--toolchain ` | Toolchain add-on (use `--list-add-ons` to see options) | | `--deployment ` | Deployment add-on (use `--list-add-ons` to see options) | | `--examples` / `--no-examples` | Include or exclude demo/example pages | diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index ecd8bb4e3..8559a2f46 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -193,6 +193,7 @@ function getCreateTelemetryProperties(projectName: string, options: CliOptions) package_manager: options.packageManager, project_name_provided: Boolean(projectName), router_only: !!options.routerOnly, + router_and_start: !!options.routerAndStart, target_dir_flag: Boolean(options.targetDir), toolchain: typeof options.toolchain === 'string' ? sanitizeId(options.toolchain) : undefined, @@ -229,6 +230,7 @@ function getResolvedCreateTelemetryProperties( intent: finalOptions.intent, package_manager: finalOptions.packageManager, router_only: !!cliOptions.routerOnly, + router_and_start: !!cliOptions.routerAndStart, toolchain: toolchain ? sanitizeId(toolchain.id) : undefined, } } @@ -810,6 +812,28 @@ export function cli({ ...options, } as CliOptions + if (cliOptions.routerAndStart) { + if (cliOptions.routerOnly) { + throw new Error( + 'Cannot combine --router-only with --router-and-start.', + ) + } + if ( + cliOptions.template && + ['typescript', 'tsx', 'javascript', 'js', 'jsx'].includes( + cliOptions.template.toLowerCase(), + ) + ) { + console.warn( + chalk.yellow( + 'Ignoring --template in favor of --router-and-start (TanStack Start).', + ), + ) + cliOptions.template = undefined + } + cliOptions.routerOnly = false + } + if (defaultRouterOnly && cliOptions.routerOnly === undefined) { cliOptions.routerOnly = true } @@ -992,6 +1016,10 @@ export function cli({ '--router-only', 'Use router-only compatibility mode (file-based routing without TanStack Start)', ) + .option( + '--router-and-start', + 'Use TanStack Start explicitly (skips the interactive router-only prompt)', + ) .option( '--blank', 'Create a minimal one-route app without default starter UI, Tailwind, devtools, or tests', diff --git a/packages/cli/src/types.ts b/packages/cli/src/types.ts index 235746ae0..cdf821faf 100644 --- a/packages/cli/src/types.ts +++ b/packages/cli/src/types.ts @@ -24,6 +24,7 @@ export interface CliOptions { addOnConfig?: string force?: boolean routerOnly?: boolean + routerAndStart?: boolean blank?: boolean template?: string tailwind?: boolean From 16d5681079e374fdace105ed9637ee328823bde6 Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Thu, 19 Nov 2026 11:54:58 -0700 Subject: [PATCH 3/5] fix(cli): preserve explicit Start intent in mode selection --- packages/cli/src/options.ts | 12 ++++- packages/cli/tests/options.test.ts | 76 ++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/options.ts b/packages/cli/src/options.ts index 5b12ed2b6..185f38dd1 100644 --- a/packages/cli/src/options.ts +++ b/packages/cli/src/options.ts @@ -96,13 +96,21 @@ export async function promptForCreateOptions( ['file-router', 'typescript', 'tsx', 'javascript', 'js', 'jsx'].includes( template, ) - const hasTemplateIntent = !!cliOptions.template || !!cliOptions.starter + const hasStartIntent = Boolean( + cliOptions.template || + cliOptions.starter || + cliOptions.blank || + (Array.isArray(cliOptions.addOns) && cliOptions.addOns.length > 0) || + cliOptions.deployment || + forcedAddOns.length > 0 || + forcedDeployment, + ) const routerOnly = !!cliOptions.routerOnly || (isLegacyTemplate ? template !== 'file-router' : false) || (cliOptions.routerOnly === undefined && !isLegacyTemplate && - !hasTemplateIntent && + !hasStartIntent && (await selectRouterOnly())) if (routerOnly) { cliOptions.routerOnly = true diff --git a/packages/cli/tests/options.test.ts b/packages/cli/tests/options.test.ts index 826af6dde..7762a8db8 100644 --- a/packages/cli/tests/options.test.ts +++ b/packages/cli/tests/options.test.ts @@ -43,6 +43,11 @@ beforeEach(() => { type: 'toolchain', modes: ['file-router'], }, + { + id: 'cloudflare', + type: 'deployment', + modes: ['file-router'], + }, ], supportedModes: { 'file-router': { @@ -69,6 +74,7 @@ const baseCliOptions: CliOptions = { } function setBasicSpies() { + vi.spyOn(prompts, 'selectRouterOnly').mockResolvedValue(false) vi.spyOn(commandLine, 'listTemplateChoices').mockImplementation(async () => []) vi .spyOn(commandLine, 'resolveStarterSpecifier') @@ -327,3 +333,73 @@ describe('promptForCreateOptions', () => { expect(options?.typescript).toBe(true) }) }) + + +describe('interactive Router-only selection', () => { + it.each([ + { + label: 'explicit add-ons', + flags: { addOns: ['react-query'] }, + defaults: {}, + expected: ['react-query'], + }, + { + label: 'explicit deployment', + flags: { deployment: 'cloudflare' }, + defaults: {}, + expected: ['cloudflare'], + }, + { + label: 'blank preset', + flags: { blank: true }, + defaults: {}, + expected: [], + }, + { + label: 'forced add-ons', + flags: {}, + defaults: { forcedAddOns: ['react-query'] }, + expected: ['react-query'], + }, + { + label: 'forced deployment', + flags: {}, + defaults: { forcedDeployment: 'cloudflare' }, + expected: ['cloudflare'], + }, + ])('keeps Start mode for $label', async ({ flags, defaults, expected }) => { + setBasicSpies() + vi.spyOn(prompts, 'selectRouterOnly').mockResolvedValue(true) + vi.spyOn(prompts, 'selectDeployment').mockImplementation( + async (_framework, provided, forced) => provided ?? forced, + ) + const cliOptions: CliOptions = { + ...baseCliOptions, + projectName: 'start-intent', + git: false, + install: false, + ...flags, + } + const result = await promptForCreateOptions(cliOptions, defaults) + expect(prompts.selectRouterOnly).not.toHaveBeenCalled() + expect(cliOptions.routerOnly).not.toBe(true) + expect(result?.chosenAddOns.map((addOn) => addOn.id)).toEqual(expected) + }) + + it('still offers Router-only when only a toolchain is requested', async () => { + setBasicSpies() + vi.spyOn(prompts, 'selectRouterOnly').mockResolvedValue(true) + vi.spyOn(prompts, 'selectToolchain').mockResolvedValue('biome') + const cliOptions: CliOptions = { + ...baseCliOptions, + projectName: 'router-choice', + toolchain: 'biome', + git: false, + install: false, + } + const result = await promptForCreateOptions(cliOptions, {}) + expect(prompts.selectRouterOnly).toHaveBeenCalledOnce() + expect(cliOptions.routerOnly).toBe(true) + expect(result?.chosenAddOns.map((addOn) => addOn.id)).toEqual(['biome']) + }) +}) From 5d6c92e871c0f29491cf8d78d1271b2eca5eb06c Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Thu, 19 Nov 2026 12:31:00 -0700 Subject: [PATCH 4/5] fix(cli): normalize explicit Start template aliases --- .changeset/interactive-router-mode.md | 5 +++ packages/cli/src/cli.ts | 2 +- packages/cli/tests-e2e/blank-smoke.spec.ts | 48 ++++++++++++++++++++++ 3 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 .changeset/interactive-router-mode.md diff --git a/.changeset/interactive-router-mode.md b/.changeset/interactive-router-mode.md new file mode 100644 index 000000000..8c9c619c1 --- /dev/null +++ b/.changeset/interactive-router-mode.md @@ -0,0 +1,5 @@ +--- +"@tanstack/cli": minor +--- + +Offer Router-only scaffolding interactively and add `--router-and-start` to choose Start explicitly. Preserve requested Start integrations when selecting the app mode or using legacy template aliases. diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index 8559a2f46..909e80639 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -821,7 +821,7 @@ export function cli({ if ( cliOptions.template && ['typescript', 'tsx', 'javascript', 'js', 'jsx'].includes( - cliOptions.template.toLowerCase(), + cliOptions.template.trim().toLowerCase(), ) ) { console.warn( diff --git a/packages/cli/tests-e2e/blank-smoke.spec.ts b/packages/cli/tests-e2e/blank-smoke.spec.ts index e3f5635a6..ca812382a 100644 --- a/packages/cli/tests-e2e/blank-smoke.spec.ts +++ b/packages/cli/tests-e2e/blank-smoke.spec.ts @@ -252,3 +252,51 @@ test('@blocking creates a production-valid blank React app', async ({ } } }) + + +for (const template of [' tsx ', ' TypeScript ']) { + test(`@blocking preserves explicit Start integrations with legacy alias ${JSON.stringify(template)}`, async () => { + const rootDir = await mkdtemp(join(tmpdir(), 'tanstack-explicit-start-')) + try { + await execFileAsync( + process.execPath, + [ + getRepoPath('packages/cli/dist/index.js'), + 'create', + 'start-app', + '--router-and-start', + '--template', + template, + '--add-ons', + 'tanstack-query', + '--deployment', + 'cloudflare', + '--toolchain', + 'biome', + '--package-manager', + 'npm', + '--yes', + '--no-install', + '--no-git', + '--no-intent', + ], + { cwd: rootDir, encoding: 'utf8' }, + ) + const appDir = join(rootDir, 'start-app') + const config = JSON.parse( + await readFile(join(appDir, '.cta.json'), 'utf8'), + ) + const pkg = JSON.parse( + await readFile(join(appDir, 'package.json'), 'utf8'), + ) + expect(config.routerOnly).toBe(false) + expect(config.chosenAddOns).toEqual( + expect.arrayContaining(['tanstack-query', 'cloudflare']), + ) + expect(pkg.dependencies['@tanstack/react-start']).toBeDefined() + expect(pkg.dependencies['@tanstack/react-query']).toBeDefined() + } finally { + await rm(rootDir, { recursive: true, force: true }) + } + }) +} From f768957073740d36f61555f9df013f067c40ebaf Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Thu, 19 Nov 2026 14:05:41 -0700 Subject: [PATCH 5/5] fix(cli): preserve legacy template ID intent --- packages/cli/src/options.ts | 1 + packages/cli/tests/options.test.ts | 6 ++++++ 2 files changed, 7 insertions(+) diff --git a/packages/cli/src/options.ts b/packages/cli/src/options.ts index f297e5338..2589dffa0 100644 --- a/packages/cli/src/options.ts +++ b/packages/cli/src/options.ts @@ -124,6 +124,7 @@ export async function promptForCreateOptions( ) const hasStartIntent = Boolean( cliOptions.template || + cliOptions.templateId || cliOptions.starter || cliOptions.blank || (Array.isArray(cliOptions.addOns) && cliOptions.addOns.length > 0) || diff --git a/packages/cli/tests/options.test.ts b/packages/cli/tests/options.test.ts index c82120fd4..6fb919750 100644 --- a/packages/cli/tests/options.test.ts +++ b/packages/cli/tests/options.test.ts @@ -474,6 +474,12 @@ describe('interactive Router-only selection', () => { defaults: {}, expected: ['cloudflare'], }, + { + label: 'legacy template id', + flags: { templateId: 'blog' }, + defaults: {}, + expected: [], + }, { label: 'blank preset', flags: { blank: true },