feat: add dev watch command for framework development (#141)

* 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

* feat: improve dev watch command output with tree-style formatting

- Replace emoji-based logging with cleaner tree-style output
- Add visual hierarchy for build progress and file changes
- Show inline diffs with proper indentation
- Reduce visual noise while maintaining all important information
- Create silent environment for initial app creation to avoid duplicate output

* docs: add --dev-watch command documentation to CONTRIBUTING.md

- Add comprehensive guide for using the --dev-watch feature
- Include example workflow with real command examples
- Document auto-rebuild and live reload capabilities
- Update pnpm-lock.yaml after merge

---------

Co-authored-by: Jack Herrington <jherr@pobox.com>

Author: timoconnellaus

CONTRIBUTING.md

@@ -40,6 +40,38 @@ npm_config_user_agent=pnpm node ../create-tsrouter-app/cli/create-start-app/dist
 
 If you want to specify a package manager.
 
+# Framework Development with --dev-watch
+
+The `--dev-watch` command provides real-time feedback while developing frameworks, add-ons, and starters. It watches for changes in your framework files and automatically rebuilds them.
+
+## Using --dev-watch
+
+To start developing a framework with live rebuilding:
+
+```bash
+node [root of the monorepo]/cli/create-tsrouter-app/dist/index.js --dev-watch ./frameworks/react-cra test-app --template typescript --package-manager bun --tailwind --add-ons shadcn
+```
+
+This command will:
+
+- Watch the selected folder for changes (the folder with the add-ons in it)
+- Automatically rebuild your app / install packages in the target folder when changes are detected (in this case it will install the shadcn addon)
+- Show build output, diffs detected and any errors in real-time
+
+## Example Workflow
+
+1. Start the dev watch mode:
+
+   ```bash
+   pnpm dev # Build in watch mode
+   rm -rf test-app && node cli/create-tsrouter-app/dist/index.js --dev-watch ./frameworks/react-cra test-app --template typescript --package-manager bun --tailwind --add-ons shadcn
+   cd my-test-app && pnpm run dev # run the tsrouter vite app
+   ```
+
+2. Select the framework you want to work on from the displayed list
+
+3. Make changes to the add-ons - they will be automatically rebuilt and your vite app will reflect the changes
+
 # Testing Add-ons and Starters
 
 Create the add-on or starter using the CLI. Then serve it locally from the project directory using `npx static-server`.

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()
@@ -15,4 +21,8 @@ cli({
   showDeploymentOptions: true,
   forcedDeployment: 'nitro',
   craCompatible: true,
+  frameworkDefinitionInitializers: [
+    createReactCraFrameworkDefinitionInitalizer,
+    createSolidFrameworkDefinitionInitalizer,
+  ],
 })

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'
 import { createFileRoute } from '@tanstack/react-router'

packages/cta-cli/package.json

@@ -38,13 +38,18 @@
     "@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",
     "validate-npm-package-name": "^7.0.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

@@ -24,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, deployments, modes, etc.
 
@@ -44,6 +49,7 @@ export function cli({
   defaultFramework,
   craCompatible = false,
   webBase,
+  frameworkDefinitionInitializers,
   showDeploymentOptions = false,
 }: {
   name: string
@@ -55,6 +61,7 @@ export function cli({
   defaultFramework?: string
   craCompatible?: boolean
   webBase?: string
+  frameworkDefinitionInitializers?: Array<() => FrameworkDefinition>
   showDeploymentOptions?: boolean
 }) {
   const environment = createUIEnvironment(appName, false)
@@ -293,6 +300,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`,
@@ -307,6 +315,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 (deployments.size > 0) {
     program.option<string>(
@@ -462,6 +474,73 @@ 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 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 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()
     } 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,
@@ -158,6 +159,7 @@ export async function normalizeOptions(
       getPackageManager() ||
       DEFAULT_PACKAGE_MANAGER,
     git: !!cliOptions.git,
+    install: cliOptions.install,
     chosenAddOns,
     addOnOptions: {
       ...populateAddOnOptionsDefaults(chosenAddOns),
@@ -166,3 +168,52 @@ export async function normalizeOptions(
     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 }
+}