fix(cli): handle deprecated create-tsrouter flags

Add explicit compatibility handling for legacy --router-only and --template flags in tanstack create, with deprecation warnings and clear errors for unsupported JavaScript templates.

Fixes #331

Author: tannerlinsley

.changeset/smart-penguins-enjoy.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/cli": patch
+---
+
+Add compatibility handling for legacy `--router-only` and `--template` create flags, including clear deprecation warnings and explicit errors for unsupported JavaScript templates.

packages/cli/src/cli.ts

@@ -24,7 +24,11 @@ import { launchUI } from '@tanstack/create-ui'
 import { runMCPServer } from './mcp.js'
 
 import { promptForAddOns, promptForCreateOptions } from './options.js'
-import { normalizeOptions, validateDevWatchOptions } from './command-line.js'
+import {
+  normalizeOptions,
+  validateDevWatchOptions,
+  validateLegacyCreateFlags,
+} from './command-line.js'
 
 import { createUIEnvironment } from './ui-environment.js'
 import { DevWatchManager } from './dev-watch.js'
@@ -96,6 +100,16 @@ export function cli({
 
   // Helper to create the create command action handler
   async function handleCreate(projectName: string, options: CliOptions) {
+    const legacyCreateFlags = validateLegacyCreateFlags(options)
+    if (legacyCreateFlags.error) {
+      log.error(legacyCreateFlags.error)
+      process.exit(1)
+    }
+
+    for (const warning of legacyCreateFlags.warnings) {
+      log.warn(warning)
+    }
+
     if (options.listAddOns) {
       const addOns = await getAllAddOns(
         getFrameworkByName(options.framework || defaultFramework || 'React')!,
@@ -386,6 +400,14 @@ export function cli({
         '--dev-watch <path>',
         'Watch a framework directory for changes and auto-rebuild',
       )
+      .option(
+        '--router-only',
+        'Deprecated: compatibility flag from create-tsrouter-app',
+      )
+      .option(
+        '--template <type>',
+        'Deprecated: compatibility flag from create-tsrouter-app',
+      )
 
     if (deployments.size > 0) {
       cmd.option<string>(
@@ -461,7 +483,7 @@ export function cli({
   }
 
   // === CREATE SUBCOMMAND ===
-  // By default creates a TanStack Start app. Use --router-only for SPA without Start.
+  // Creates a TanStack Start app (file-router mode).
   const createCommand = program
     .command('create')
     .description(`Create a new TanStack Start application`)

packages/cli/src/command-line.ts

@@ -19,6 +19,52 @@ import type { Options } from '@tanstack/create'
 
 import type { CliOptions } from './types.js'
 
+const SUPPORTED_LEGACY_TEMPLATES = new Set([
+  'file-router',
+  'typescript',
+  'tsx',
+])
+
+export function validateLegacyCreateFlags(cliOptions: CliOptions): {
+  warnings: Array<string>
+  error?: string
+} {
+  const warnings: Array<string> = []
+
+  if (cliOptions.routerOnly) {
+    warnings.push(
+      'The --router-only flag is deprecated and ignored. `tanstack create` already creates router-based apps.',
+    )
+  }
+
+  if (!cliOptions.template) {
+    return { warnings }
+  }
+
+  const template = cliOptions.template.toLowerCase().trim()
+
+  if (template === 'javascript' || template === 'js' || template === 'jsx') {
+    return {
+      warnings,
+      error:
+        'JavaScript/JSX templates are not supported. TanStack Start file-router templates are TypeScript-only.',
+    }
+  }
+
+  if (!SUPPORTED_LEGACY_TEMPLATES.has(template)) {
+    return {
+      warnings,
+      error: `Invalid --template value: ${cliOptions.template}. Supported values are: file-router, typescript, tsx.`,
+    }
+  }
+
+  warnings.push(
+    'The --template flag is deprecated. TypeScript/TSX is the default and only supported template.',
+  )
+
+  return { warnings }
+}
+
 export async function normalizeOptions(
   cliOptions: CliOptions,
   forcedAddOns?: Array<string>,

packages/cli/src/types.ts

@@ -20,4 +20,6 @@ export interface CliOptions {
   install?: boolean
   addOnConfig?: string
   force?: boolean
+  routerOnly?: boolean
+  template?: string
 }

packages/cli/tests/command-line.test.ts

@@ -1,7 +1,10 @@
 import { basename, resolve } from 'node:path'
 import { beforeEach, describe, expect, it } from 'vitest'
 
-import { normalizeOptions } from '../src/command-line.js'
+import {
+  normalizeOptions,
+  validateLegacyCreateFlags,
+} from '../src/command-line.js'
 import {
   sanitizePackageName,
   getCurrentDirectoryName,
@@ -273,3 +276,33 @@ describe('normalizeOptions', () => {
     expect(options?.chosenAddOns.map((a) => a.id).includes('baz')).toBe(true)
   })
 })
+
+describe('validateLegacyCreateFlags', () => {
+  it('returns no warnings or errors without legacy flags', () => {
+    const result = validateLegacyCreateFlags({})
+    expect(result.warnings).toEqual([])
+    expect(result.error).toBeUndefined()
+  })
+
+  it('warns when --router-only is used', () => {
+    const result = validateLegacyCreateFlags({ routerOnly: true })
+    expect(result.error).toBeUndefined()
+    expect(result.warnings[0]).toContain('--router-only')
+  })
+
+  it('errors for JavaScript templates', () => {
+    const result = validateLegacyCreateFlags({ template: 'javascript' })
+    expect(result.error).toContain('JavaScript/JSX templates are not supported')
+  })
+
+  it('errors for unknown template values', () => {
+    const result = validateLegacyCreateFlags({ template: 'foo' })
+    expect(result.error).toContain('Invalid --template value')
+  })
+
+  it('warns for supported deprecated template values', () => {
+    const result = validateLegacyCreateFlags({ template: 'tsx' })
+    expect(result.error).toBeUndefined()
+    expect(result.warnings[0]).toContain('--template')
+  })
+})