feat: add dev watch command for framework development

Addition of a --dev-watch cli arg so that when working on add-ons you can continually scaffold an app when changes are detected

- add --dev-watch cli arg e.g. --dev-watch ./frameworks/react-cra
- add --no-install cli arg - skips install deps. Needed so we aren't installing deps when package.json doesn't change in --dev-watch

Author: timoconnellaus

cli/create-start-app/src/index.ts

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 import { cli } from '@tanstack/cta-cli'
 
-import { register as registerReactCra } from '@tanstack/cta-framework-react-cra'
-import { register as registerSolid } from '@tanstack/cta-framework-solid'
+import {
+  createFrameworkDefinition as createReactCraFrameworkDefinitionInitalizer,
+  register as registerReactCra,
+} from '@tanstack/cta-framework-react-cra'
+import {
+  createFrameworkDefinition as createSolidFrameworkDefinitionInitalizer,
+  register as registerSolid,
+} from '@tanstack/cta-framework-solid'
 
 registerReactCra()
 registerSolid()
@@ -13,4 +19,8 @@ cli({
   forcedMode: 'file-router',
   forcedAddOns: ['start'],
   craCompatible: true,
+  frameworkDefinitionInitializers: [
+    createReactCraFrameworkDefinitionInitalizer,
+    createSolidFrameworkDefinitionInitalizer,
+  ],
 })

frameworks/react-cra/add-ons/start/assets/src/routes/api.demo-names.ts

@@ -1,4 +1,6 @@
-export const ServerRoute = createServerFileRoute().methods({
+import { createServerFileRoute } from '@tanstack/react-start/server'
+
+export const ServerRoute = createServerFileRoute('/api/demo-names').methods({
   GET: async ({ request }) => {
     return new Response(JSON.stringify(['Alice', 'Bob', 'Charlie']), {
       headers: {

frameworks/react-cra/add-ons/tRPC/assets/src/routes/api.trpc.$.tsx

@@ -1,3 +1,4 @@
+import { createServerFileRoute } from '@tanstack/react-start/server'
 import { fetchRequestHandler } from '@trpc/server/adapters/fetch'
 import { trpcRouter } from '@/integrations/trpc/router'
 

packages/cta-cli/package.json

@@ -37,13 +37,17 @@
     "@tanstack/cta-engine": "workspace:*",
     "@tanstack/cta-ui": "workspace:*",
     "chalk": "^5.4.1",
+    "chokidar": "^3.6.0",
     "commander": "^13.1.0",
+    "diff": "^7.0.0",
     "express": "^4.21.2",
     "semver": "^7.7.2",
+    "tempy": "^3.1.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {
     "@tanstack/config": "^0.16.2",
+    "@types/diff": "^5.2.0",
     "@types/express": "^5.0.1",
     "@types/node": "^22.13.4",
     "@types/semver": "^7.7.0",

packages/cta-cli/src/cli.ts

@@ -13,7 +13,6 @@ import {
   createApp,
   createSerializedOptions,
   getAllAddOns,
-  getFrameworkById,
   getFrameworkByName,
   getFrameworks,
   initAddOn,
@@ -25,13 +24,18 @@ import { launchUI } from '@tanstack/cta-ui'
 import { runMCPServer } from './mcp.js'
 
 import { promptForAddOns, promptForCreateOptions } from './options.js'
-import { normalizeOptions } from './command-line.js'
+import { normalizeOptions, validateDevWatchOptions } from './command-line.js'
 
 import { createUIEnvironment } from './ui-environment.js'
 import { convertTemplateToMode } from './utils.js'
+import { DevWatchManager } from './dev-watch.js'
 
 import type { CliOptions, TemplateOptions } from './types.js'
-import type { Options, PackageManager } from '@tanstack/cta-engine'
+import type {
+  FrameworkDefinition,
+  Options,
+  PackageManager,
+} from '@tanstack/cta-engine'
 
 // This CLI assumes that all of the registered frameworks have the same set of toolchains, modes, etc.
 
@@ -44,6 +48,7 @@ export function cli({
   defaultFramework,
   craCompatible = false,
   webBase,
+  frameworkDefinitionInitializers,
 }: {
   name: string
   appName: string
@@ -53,6 +58,7 @@ export function cli({
   defaultFramework?: string
   craCompatible?: boolean
   webBase?: string
+  frameworkDefinitionInitializers?: Array<() => FrameworkDefinition>
 }) {
   const environment = createUIEnvironment(appName, false)
 
@@ -280,6 +286,7 @@ Remove your node_modules directory and package lock file and re-install.`,
       'initialize this project from a starter URL',
       false,
     )
+    .option('--no-install', 'skip installing dependencies')
     .option<PackageManager>(
       `--package-manager <${SUPPORTED_PACKAGE_MANAGERS.join('|')}>`,
       `Explicitly tell the CLI to use this package manager`,
@@ -294,6 +301,10 @@ Remove your node_modules directory and package lock file and re-install.`,
         return value as PackageManager
       },
     )
+    .option(
+      '--dev-watch <path>',
+      'Watch a framework directory for changes and auto-rebuild',
+    )
 
   if (toolchains.size > 0) {
     program.option<string>(
@@ -352,6 +363,67 @@ Remove your node_modules directory and package lock file and re-install.`,
         forcedAddOns,
         appName,
       })
+    } else 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,
+        },
+        defaultMode,
+        forcedAddOns,
+      )
+
+      if (!normalizedOpts) {
+        throw new Error('Failed to normalize options')
+      }
+
+      normalizedOpts.targetDir =
+        options.targetDir || resolve(process.cwd(), projectName)
+
+      // Create the initial app
+      intro(`Creating initial ${appName} app in ${normalizedOpts.targetDir}...`)
+      await createApp(environment, normalizedOpts)
+
+      // 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()
     } else {
       try {
         const cliOptions = {

packages/cta-cli/src/command-line.ts

@@ -1,4 +1,5 @@
 import { resolve } from 'node:path'
+import fs from 'node:fs'
 
 import {
   DEFAULT_PACKAGE_MANAGER,
@@ -114,7 +115,57 @@ export async function normalizeOptions(
       getPackageManager() ||
       DEFAULT_PACKAGE_MANAGER,
     git: !!cliOptions.git,
+    install: cliOptions.install,
     chosenAddOns,
     starter: starter,
   }
 }
+
+export function validateDevWatchOptions(cliOptions: CliOptions): {
+  valid: boolean
+  error?: string
+} {
+  if (!cliOptions.devWatch) {
+    return { valid: true }
+  }
+
+  // Validate watch path exists
+  const watchPath = resolve(process.cwd(), cliOptions.devWatch)
+  if (!fs.existsSync(watchPath)) {
+    return {
+      valid: false,
+      error: `Watch path does not exist: ${watchPath}`,
+    }
+  }
+
+  // Validate it's a directory
+  const stats = fs.statSync(watchPath)
+  if (!stats.isDirectory()) {
+    return {
+      valid: false,
+      error: `Watch path is not a directory: ${watchPath}`,
+    }
+  }
+
+  // Ensure target directory is specified
+  if (!cliOptions.projectName && !cliOptions.targetDir) {
+    return {
+      valid: false,
+      error: 'Project name or target directory is required for dev watch mode',
+    }
+  }
+
+  // Check for framework structure
+  const hasAddOns = fs.existsSync(resolve(watchPath, 'add-ons'))
+  const hasAssets = fs.existsSync(resolve(watchPath, 'assets'))
+  const hasFrameworkJson = fs.existsSync(resolve(watchPath, 'framework.json'))
+
+  if (!hasAddOns && !hasAssets && !hasFrameworkJson) {
+    return {
+      valid: false,
+      error: `Watch path does not appear to be a valid framework directory: ${watchPath}`,
+    }
+  }
+
+  return { valid: true }
+}