@tanstack/cli 0.59.7 → 0.60.0

package/playwright.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests-e2e',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  workers: 1,
+  timeout: 10 * 60 * 1000,
+  expect: {
+    timeout: 20 * 1000,
+  },
+  reporter: process.env.CI ? [['github'], ['html', { open: 'never' }]] : 'list',
+  use: {
+    ...devices['Desktop Chrome'],
+    channel: 'chrome',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+})

package/src/bin.ts

@@ -1,7 +1,15 @@
 #!/usr/bin/env node
 import { cli } from './cli.js'
+import {
+  createReactFrameworkDefinition,
+  createSolidFrameworkDefinition,
+} from '@tanstack/create'
 
 cli({
   name: 'tanstack',
   appName: 'TanStack',
+  frameworkDefinitionInitializers: [
+    createReactFrameworkDefinition,
+    createSolidFrameworkDefinition,
+  ],
 })

package/src/cli.ts

@@ -9,10 +9,9 @@ import {
   SUPPORTED_PACKAGE_MANAGERS,
   addToApp,
   compileAddOn,
-  devAddOn,
   compileStarter,
   createApp,
-  createSerializedOptions,
+  devAddOn,
   getAllAddOns,
   getFrameworkByName,
   getFrameworks,
@@ -20,8 +19,6 @@ import {
   initStarter,
 } from '@tanstack/create'
 
-import { launchUI } from '@tanstack/create-ui'
-
 import { runMCPServer } from './mcp.js'
 
 import { promptForAddOns, promptForCreateOptions } from './options.js'
@@ -52,7 +49,6 @@ export function cli({
   forcedAddOns = [],
   forcedDeployment,
   defaultFramework,
-  webBase,
   frameworkDefinitionInitializers,
   showDeploymentOptions = false,
   legacyAutoCreate = false,
@@ -63,7 +59,6 @@ export function cli({
   forcedAddOns?: Array<string>
   forcedDeployment?: string
   defaultFramework?: string
-  webBase?: string
   frameworkDefinitionInitializers?: Array<() => FrameworkDefinition>
   showDeploymentOptions?: boolean
   legacyAutoCreate?: boolean
@@ -106,6 +101,91 @@ export function cli({
 
   const availableFrameworks = getFrameworks().map((f) => f.name)
 
+  function resolveBuiltInDevWatchPath(frameworkId: string): string {
+    const candidates = [
+      resolve(process.cwd(), 'packages/create/src/frameworks', frameworkId),
+      resolve(process.cwd(), '../create/src/frameworks', frameworkId),
+    ]
+
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        return candidate
+      }
+    }
+
+    return candidates[0]
+  }
+
+  async function startDevWatchMode(projectName: string, options: CliOptions) {
+    // Validate dev watch options
+    const validation = validateDevWatchOptions({ ...options, projectName })
+    if (!validation.valid) {
+      console.error(validation.error)
+      process.exit(1)
+    }
+
+    // Enter dev watch mode
+    if (!projectName && !options.targetDir) {
+      console.error('Project name/target directory is required for dev watch mode')
+      process.exit(1)
+    }
+
+    if (!options.framework) {
+      console.error('Failed to detect framework')
+      process.exit(1)
+    }
+
+    const framework = getFrameworkByName(options.framework)
+    if (!framework) {
+      console.error('Failed to detect framework')
+      process.exit(1)
+    }
+
+    // First, create the app normally using the standard flow
+    const normalizedOpts = await normalizeOptions(
+      {
+        ...options,
+        projectName,
+        framework: framework.id,
+      },
+      forcedAddOns,
+    )
+
+    if (!normalizedOpts) {
+      throw new Error('Failed to normalize options')
+    }
+
+    normalizedOpts.targetDir =
+      options.targetDir || resolve(process.cwd(), projectName)
+
+    // Create the initial app with minimal output for dev watch mode
+    console.log(chalk.bold('\ndev-watch'))
+    console.log(chalk.gray('├─') + ' ' + `creating initial ${appName} app...`)
+    if (normalizedOpts.install !== false) {
+      console.log(
+        chalk.gray('├─') + ' ' + chalk.yellow('⟳') + ' installing packages...',
+      )
+    }
+    const silentEnvironment = createUIEnvironment(appName, true)
+    await confirmTargetDirectorySafety(normalizedOpts.targetDir, options.force)
+    await createApp(silentEnvironment, normalizedOpts)
+    console.log(chalk.gray('└─') + ' ' + chalk.green('✓') + ` app created`)
+
+    // Now start the dev watch mode
+    const manager = new DevWatchManager({
+      watchPath: options.devWatch!,
+      targetDir: normalizedOpts.targetDir,
+      framework,
+      cliOptions: normalizedOpts,
+      packageManager: normalizedOpts.packageManager,
+      runDevCommand: options.runDev,
+      environment,
+      frameworkDefinitionInitializers,
+    })
+
+    await manager.start()
+  }
+
   const toolchains = new Set<string>()
   for (const framework of getFrameworks()) {
     for (const addOn of framework.getAddOns()) {
@@ -235,72 +315,7 @@ export function cli({
     }
 
     if (options.devWatch) {
-      // Validate dev watch options
-      const validation = validateDevWatchOptions({ ...options, projectName })
-      if (!validation.valid) {
-        console.error(validation.error)
-        process.exit(1)
-      }
-
-      // Enter dev watch mode
-      if (!projectName && !options.targetDir) {
-        console.error(
-          'Project name/target directory is required for dev watch mode',
-        )
-        process.exit(1)
-      }
-
-      if (!options.framework) {
-        console.error('Failed to detect framework')
-        process.exit(1)
-      }
-
-      const framework = getFrameworkByName(options.framework)
-      if (!framework) {
-        console.error('Failed to detect framework')
-        process.exit(1)
-      }
-
-      // First, create the app normally using the standard flow
-      const normalizedOpts = await normalizeOptions(
-        {
-          ...options,
-          projectName,
-          framework: framework.id,
-        },
-        forcedAddOns,
-      )
-
-      if (!normalizedOpts) {
-        throw new Error('Failed to normalize options')
-      }
-
-      normalizedOpts.targetDir =
-        options.targetDir || resolve(process.cwd(), projectName)
-
-      // Create the initial app with minimal output for dev watch mode
-      console.log(chalk.bold('\ndev-watch'))
-      console.log(chalk.gray('├─') + ' ' + `creating initial ${appName} app...`)
-      if (normalizedOpts.install !== false) {
-        console.log(chalk.gray('├─') + ' ' + chalk.yellow('⟳') + ' installing packages...')
-      }
-      const silentEnvironment = createUIEnvironment(appName, true)
-      await confirmTargetDirectorySafety(normalizedOpts.targetDir, options.force)
-      await createApp(silentEnvironment, normalizedOpts)
-      console.log(chalk.gray('└─') + ' ' + chalk.green('✓') + ` app created`)
-
-      // Now start the dev watch mode
-      const manager = new DevWatchManager({
-        watchPath: options.devWatch,
-        targetDir: normalizedOpts.targetDir,
-        framework,
-        cliOptions: normalizedOpts,
-        packageManager: normalizedOpts.packageManager,
-        environment,
-        frameworkDefinitionInitializers,
-      })
-
-      await manager.start()
+      await startDevWatchMode(projectName, options)
       return
     }
 
@@ -317,6 +332,9 @@ export function cli({
       if (
         cliOptions.routerOnly !== true &&
         cliOptions.template &&
+        ['file-router', 'typescript', 'tsx', 'javascript', 'js', 'jsx'].includes(
+          cliOptions.template.toLowerCase(),
+        ) &&
         cliOptions.template.toLowerCase() !== 'file-router'
       ) {
         cliOptions.routerOnly = true
@@ -337,29 +355,6 @@ export function cli({
         )
       }
 
-      if (options.ui) {
-        const optionsFromCLI = await normalizeOptions(
-          cliOptions,
-          forcedAddOns,
-          { disableNameCheck: true, forcedDeployment },
-        )
-        const uiOptions = {
-          ...createSerializedOptions(optionsFromCLI!),
-          projectName: 'my-app',
-          targetDir: resolve(process.cwd(), 'my-app'),
-        }
-        launchUI({
-          mode: 'setup',
-          options: uiOptions,
-          forcedRouterMode: defaultMode,
-          forcedAddOns,
-          environmentFactory: () => createUIEnvironment(appName, false),
-          webBase,
-          showDeploymentOptions,
-        })
-        return
-      }
-
       if (finalOptions) {
         intro(`Creating a new ${appName} app in ${projectName}...`)
       } else {
@@ -411,6 +406,10 @@ export function cli({
         '--framework <type>',
         `project framework (${availableFrameworks.join(', ')})`,
         (value) => {
+          if (value.toLowerCase() === 'react-cra') {
+            return 'react'
+          }
+
           if (
             !availableFrameworks.some(
               (f) => f.toLowerCase() === value.toLowerCase(),
@@ -428,10 +427,15 @@ export function cli({
 
     cmd
       .option(
-        '--starter [url]',
-        'initialize this project from a starter URL',
+        '--starter [url-or-id]',
+        'DEPRECATED: use --template. Initializes from a template URL or built-in id',
         false,
       )
+      .option('--template-id <id>', 'initialize using a built-in template id')
+      .option(
+        '--template [url-or-id]',
+        'initialize this project from a template URL or built-in template id',
+      )
       .option('--no-install', 'skip installing dependencies')
       .option<PackageManager>(
         `--package-manager <${SUPPORTED_PACKAGE_MANAGERS.join('|')}>`,
@@ -451,14 +455,11 @@ export function cli({
         '--dev-watch <path>',
         'Watch a framework directory for changes and auto-rebuild',
       )
+      .option('--run-dev', 'Run the app dev server alongside dev-watch', false)
       .option(
         '--router-only',
         'Use router-only compatibility mode (file-based routing without TanStack Start)',
       )
-      .option(
-        '--template <type>',
-        'Deprecated: compatibility flag from create-tsrouter-app',
-      )
       .option(
         '--tailwind',
         'Deprecated: compatibility flag; Tailwind is always enabled',
@@ -530,7 +531,6 @@ export function cli({
         '--target-dir <path>',
         'the target directory for the application root',
       )
-      .option('--ui', 'Launch the UI for project creation')
       .option(
         '--add-on-config <config>',
         'JSON string with add-on configuration options',
@@ -553,6 +553,34 @@ export function cli({
   configureCreateCommand(createCommand)
   createCommand.action(handleCreate)
 
+  // === DEV SUBCOMMAND ===
+  const devCommand = program
+    .command('dev')
+    .description(
+      'Create a sandbox app and watch built-in framework templates/add-ons',
+    )
+
+  configureCreateCommand(devCommand)
+  devCommand.action(async (projectName: string, options: CliOptions) => {
+    const frameworkName = options.framework || defaultFramework || 'React'
+    const framework = getFrameworkByName(frameworkName)
+    if (!framework) {
+      console.error(`Unknown framework: ${frameworkName}`)
+      process.exit(1)
+    }
+
+    const watchPath = resolveBuiltInDevWatchPath(framework.id)
+    const devOptions: CliOptions = {
+      ...options,
+      framework: framework.name,
+      devWatch: watchPath,
+      runDev: true,
+      install: options.install ?? true,
+    }
+
+    await startDevWatchMode(projectName, devOptions)
+  })
+
   // === MCP SUBCOMMAND ===
   program
     .command('mcp')
@@ -647,8 +675,7 @@ Remove your node_modules directory and package lock file and re-install.`,
       'Name of the add-ons (or add-ons separated by spaces or commas)',
     )
     .option('--forced', 'Force the add-on to be added', false)
-    .option('--ui', 'Add with the UI')
-    .action(async (addOns: Array<string>, options: { forced: boolean; ui: boolean }) => {
+    .action(async (addOns: Array<string>, options: { forced: boolean }) => {
       const parsedAddOns: Array<string> = []
       for (const addOn of addOns) {
         if (addOn.includes(',') || addOn.includes(' ')) {
@@ -659,18 +686,7 @@ Remove your node_modules directory and package lock file and re-install.`,
           parsedAddOns.push(addOn.trim())
         }
       }
-      if (options.ui) {
-        launchUI({
-          mode: 'add',
-          addOns: parsedAddOns,
-          projectPath: resolve(process.cwd()),
-          forcedRouterMode: defaultMode,
-          forcedAddOns,
-          environmentFactory: () => createUIEnvironment(appName, false),
-          webBase,
-          showDeploymentOptions,
-        })
-      } else if (parsedAddOns.length < 1) {
+      if (parsedAddOns.length < 1) {
         const selectedAddOns = await promptForAddOns()
         if (selectedAddOns.length) {
           await addToApp(environment, selectedAddOns, resolve(process.cwd()), {
@@ -707,17 +723,32 @@ Remove your node_modules directory and package lock file and re-install.`,
       await devAddOn(environment)
     })
 
-  // === STARTER SUBCOMMAND ===
+  // === TEMPLATE SUBCOMMAND ===
+  const templateCommand = program.command('template')
+  templateCommand
+    .command('init')
+    .description('Initialize a project template from the current project')
+    .action(async () => {
+      await initStarter(environment)
+    })
+  templateCommand
+    .command('compile')
+    .description('Compile the template JSON file for the current project')
+    .action(async () => {
+      await compileStarter(environment)
+    })
+
+  // Legacy alias for template command
   const starterCommand = program.command('starter')
   starterCommand
     .command('init')
-    .description('Initialize a project starter from the current project')
+    .description('Deprecated alias: initialize a project template')
     .action(async () => {
       await initStarter(environment)
     })
   starterCommand
     .command('compile')
-    .description('Compile the starter JSON file for the current project')
+    .description('Deprecated alias: compile the template JSON file')
     .action(async () => {
       await compileStarter(environment)
     })

package/src/command-line.ts

@@ -6,6 +6,7 @@ import {
   finalizeAddOns,
   getFrameworkById,
   getPackageManager,
+  getRawRegistry,
   loadStarter,
   populateAddOnOptionsDefaults,
 } from '@tanstack/create'
@@ -25,15 +26,182 @@ const SUPPORTED_LEGACY_TEMPLATES = new Set([
   'tsx',
 ])
 
+const LEGACY_TEMPLATE_ALIASES = new Set(['javascript', 'js', 'jsx'])
+
+function getLegacyTemplateValue(templateValue?: string) {
+  if (!templateValue) {
+    return undefined
+  }
+
+  const normalized = templateValue.toLowerCase().trim()
+  if (
+    SUPPORTED_LEGACY_TEMPLATES.has(normalized) ||
+    LEGACY_TEMPLATE_ALIASES.has(normalized)
+  ) {
+    return normalized
+  }
+
+  return undefined
+}
+
+function slugifyStarterName(value: string) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function isLikelyStarterUrlOrPath(value: string) {
+  return (
+    /^https?:\/\//i.test(value) ||
+    /^file:\/\//i.test(value) ||
+    value.startsWith('./') ||
+    value.startsWith('../') ||
+    value.startsWith('/') ||
+    /^[a-zA-Z]:[\\/]/.test(value)
+  )
+}
+
+function getStarterIdsFromUrl(starterUrl: string) {
+  const ids = new Set<string>()
+
+  try {
+    const pathname = new URL(starterUrl).pathname
+    const parts = pathname.split('/').filter(Boolean)
+    const lastPart = parts.at(-1)?.toLowerCase()
+
+    if (lastPart) {
+      ids.add(lastPart.replace(/\.json$/i, ''))
+    }
+
+    if (
+      (lastPart === 'starter.json' || lastPart === 'template.json') &&
+      parts.length >= 2
+    ) {
+      ids.add(parts.at(-2)!.toLowerCase())
+    }
+  } catch {
+    // Ignore URL parse errors and rely on other id heuristics.
+  }
+
+  return ids
+}
+
+function resolveMonorepoStarterById(starterId: string) {
+  const normalized = starterId.toLowerCase().trim()
+  const idVariants = Array.from(
+    new Set([
+      normalized,
+      normalized.replace(/-template$/i, ''),
+      normalized.replace(/-starter$/i, ''),
+    ]),
+  ).filter(Boolean)
+
+  const cwd = process.cwd()
+  const rootCandidates = [
+    cwd,
+    resolve(cwd, '..'),
+    resolve(cwd, '../..'),
+    resolve(cwd, '../../..'),
+  ]
+
+  for (const root of rootCandidates) {
+    for (const framework of ['react', 'solid']) {
+      for (const id of idVariants) {
+        const templatePath = resolve(root, 'examples', framework, id, 'template.json')
+        if (fs.existsSync(templatePath)) {
+          return templatePath
+        }
+
+        const starterPath = resolve(root, 'examples', framework, id, 'starter.json')
+        if (fs.existsSync(starterPath)) {
+          return starterPath
+        }
+      }
+    }
+  }
+
+  return undefined
+}
+
+async function resolveStarterSpecifier(starterSpecifier: string) {
+  const normalized = starterSpecifier.trim()
+
+  if (!normalized || isLikelyStarterUrlOrPath(normalized)) {
+    return normalized
+  }
+
+  const registry = await getRawRegistry()
+  if (registry && registry.starters?.length) {
+    const lookup = normalized.toLowerCase()
+    const match = registry.starters.find((starter) => {
+      const candidateIds = new Set<string>()
+      candidateIds.add(starter.name.toLowerCase())
+      candidateIds.add(slugifyStarterName(starter.name))
+
+      for (const id of getStarterIdsFromUrl(starter.url)) {
+        candidateIds.add(id)
+      }
+
+      return candidateIds.has(lookup)
+    })
+
+    if (match) {
+      return match.url
+    }
+  }
+
+  const monorepoStarterPath = resolveMonorepoStarterById(normalized)
+  if (monorepoStarterPath) {
+    return monorepoStarterPath
+  }
+
+  if (!registry || !registry.starters?.length) {
+    throw new Error(
+      `Could not resolve template id "${normalized}" because no template registry is configured. Pass a template URL (or set CTA_REGISTRY).`,
+    )
+  }
+
+  const availableIds = Array.from(
+    new Set(
+      registry.starters.flatMap((starter) => {
+        const ids = [slugifyStarterName(starter.name)]
+        ids.push(...Array.from(getStarterIdsFromUrl(starter.url)))
+        return ids
+      }),
+    ),
+  )
+    .filter(Boolean)
+    .sort()
+
+  throw new Error(
+    `Unknown template id "${normalized}". Available built-in templates: ${availableIds.join(', ')}`,
+  )
+}
+
 export function validateLegacyCreateFlags(cliOptions: CliOptions): {
   warnings: Array<string>
   error?: string
 } {
   const warnings: Array<string> = []
+  const legacyTemplate = getLegacyTemplateValue(cliOptions.template)
+
+  if (cliOptions.starter) {
+    warnings.push(
+      'The --starter flag is deprecated; prefer --template instead. Backward compatibility remains for now.',
+    )
+  }
+
+  if (cliOptions.starter && cliOptions.template && !legacyTemplate) {
+    warnings.push(
+      'Both --starter and --template were provided. --template takes precedence.',
+    )
+  }
 
   if (cliOptions.routerOnly) {
     warnings.push(
-      'The --router-only flag enables router-only compatibility mode. Start-dependent add-ons, deployment adapters, and starters are disabled; only the base template and optional toolchain are supported.',
+      'The --router-only flag enables router-only compatibility mode. Start-dependent add-ons, deployment adapters, and templates are disabled; only the base template and optional toolchain are supported.',
     )
   }
 
@@ -50,7 +218,11 @@ export function validateLegacyCreateFlags(cliOptions: CliOptions): {
   }
 
   if (cliOptions.routerOnly && cliOptions.starter) {
-    warnings.push('Ignoring --starter in router-only compatibility mode.')
+    warnings.push('Ignoring --starter/--template in router-only compatibility mode.')
+  }
+
+  if (cliOptions.routerOnly && cliOptions.templateId) {
+    warnings.push('Ignoring --template-id in router-only compatibility mode.')
   }
 
   if (cliOptions.tailwind === true) {
@@ -65,11 +237,11 @@ export function validateLegacyCreateFlags(cliOptions: CliOptions): {
     )
   }
 
-  if (!cliOptions.template) {
+  if (!legacyTemplate) {
     return { warnings }
   }
 
-  const template = cliOptions.template.toLowerCase().trim()
+  const template = legacyTemplate
 
   if (template === 'javascript' || template === 'js' || template === 'jsx') {
     return {
@@ -126,13 +298,27 @@ export async function normalizeOptions(
   let mode = 'file-router'
   let routerOnly = !!cliOptions.routerOnly
 
-  const template = cliOptions.template?.toLowerCase().trim()
+  const legacyTemplate = getLegacyTemplateValue(cliOptions.template)
+
+  if (!cliOptions.starter) {
+    if (cliOptions.template && !legacyTemplate) {
+      cliOptions.starter = cliOptions.template
+    } else if (cliOptions.templateId) {
+      cliOptions.starter = cliOptions.templateId
+    }
+  }
+
+  const template = legacyTemplate
   if (template && template !== 'file-router') {
     routerOnly = true
   }
 
+  if (!cliOptions.starter && cliOptions.templateId) {
+    cliOptions.starter = cliOptions.templateId
+  }
+
   const starter = !routerOnly && cliOptions.starter
-    ? await loadStarter(cliOptions.starter)
+    ? await loadStarter(await resolveStarterSpecifier(cliOptions.starter))
     : undefined
 
   // TypeScript and Tailwind are always enabled with TanStack Start
@@ -144,7 +330,7 @@ export async function normalizeOptions(
     mode = starter.mode
   }
 
-  const framework = getFrameworkById(cliOptions.framework || 'react-cra')!
+  const framework = getFrameworkById(cliOptions.framework || 'react')!
 
   async function selectAddOns() {
     // Edge case for Windows Powershell