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/docs/cli-reference.md b/docs/cli-reference.md index fdc1a3ae1..d9522ad86 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -20,6 +20,7 @@ tanstack create [project-name] [options] | `--framework ` | `React`, `Solid` | | `--build-tool ` | `vite` (default), `rsbuild` | | `--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 4803fcf21..822047304 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -196,6 +196,7 @@ export function getCreateTelemetryProperties(projectName: string, options: CliOp 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, @@ -233,6 +234,7 @@ export function getResolvedCreateTelemetryProperties( intent: finalOptions.intent, package_manager: finalOptions.packageManager, router_only: !!cliOptions.routerOnly, + router_and_start: !!cliOptions.routerAndStart, toolchain: toolchain ? sanitizeId(toolchain.id) : undefined, } } @@ -826,6 +828,29 @@ 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.trim().toLowerCase(), + ) + ) { + console.warn( + styleText( + '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 } @@ -1025,6 +1050,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/options.ts b/packages/cli/src/options.ts index a12a2428b..2589dffa0 100644 --- a/packages/cli/src/options.ts +++ b/packages/cli/src/options.ts @@ -24,6 +24,7 @@ import { selectGit, selectInstall, selectPackageManager, + selectRouterOnly, selectTemplate, selectToolchain, } from './ui-prompts.js' @@ -121,9 +122,26 @@ export async function promptForCreateOptions( ['file-router', 'typescript', 'tsx', 'javascript', 'js', 'jsx'].includes( template, ) + const hasStartIntent = Boolean( + cliOptions.template || + cliOptions.templateId || + 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) + (isLegacyTemplate ? template !== 'file-router' : false) || + (cliOptions.routerOnly === undefined && + !isLegacyTemplate && + !hasStartIntent && + (await selectRouterOnly())) + if (routerOnly) { + cliOptions.routerOnly = true + } if (!cliOptions.starter) { if (cliOptions.template && !isLegacyTemplate) { diff --git a/packages/cli/src/types.ts b/packages/cli/src/types.ts index 83ddb836d..ba41d6931 100644 --- a/packages/cli/src/types.ts +++ b/packages/cli/src/types.ts @@ -25,6 +25,7 @@ export interface CliOptions { addOnConfig?: string force?: boolean routerOnly?: boolean + routerAndStart?: boolean blank?: boolean template?: string tailwind?: boolean diff --git a/packages/cli/src/ui-prompts.ts b/packages/cli/src/ui-prompts.ts index 95857fd93..59b03dc95 100644 --- a/packages/cli/src/ui-prompts.ts +++ b/packages/cli/src/ui-prompts.ts @@ -87,6 +87,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?', diff --git a/packages/cli/tests-e2e/blank-smoke.spec.ts b/packages/cli/tests-e2e/blank-smoke.spec.ts index 01fad0d8f..7fa4fe287 100644 --- a/packages/cli/tests-e2e/blank-smoke.spec.ts +++ b/packages/cli/tests-e2e/blank-smoke.spec.ts @@ -251,3 +251,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 }) + } + }) +} diff --git a/packages/cli/tests/options.test.ts b/packages/cli/tests/options.test.ts index 35de7586c..6fb919750 100644 --- a/packages/cli/tests/options.test.ts +++ b/packages/cli/tests/options.test.ts @@ -56,6 +56,11 @@ beforeEach(() => { modes: ['file-router'], exclusive: ['linter'], }, + { + id: 'cloudflare', + type: 'deployment', + modes: ['file-router'], + }, { id: 'eslint', type: 'toolchain', @@ -93,6 +98,7 @@ const baseCliOptions: CliOptions = { } function setBasicSpies() { + vi.spyOn(prompts, 'selectRouterOnly').mockResolvedValue(false) vi.spyOn(prompts, 'selectBundler').mockImplementation(async () => 'vite') vi.spyOn(commandLine, 'listTemplateChoices').mockImplementation(async () => []) vi @@ -453,3 +459,78 @@ describe('promptForAddOns', () => { expect(prompts.selectAddOns).not.toHaveBeenCalled() }) }) + +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: 'legacy template id', + flags: { templateId: 'blog' }, + defaults: {}, + expected: [], + }, + { + 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']) + }) +})