feat(create): add add-on dev watch mode

Author: tannerlinsley

docs/creating-add-ons.md

@@ -26,6 +26,9 @@ tanstack add-on init
 # 5. Compile
 tanstack add-on compile
 
+# Optional: continuously rebuild while authoring
+tanstack add-on dev
+
 # 6. Test locally
 npx serve .add-on -l 9080
 tanstack create test --add-ons http://localhost:9080/info.json
@@ -193,6 +196,8 @@ npx serve .add-on -l 9080
 tanstack create test-app --add-ons http://localhost:9080/info.json
 ```
 
+If you are actively editing templates, run `tanstack add-on dev` to auto-refresh `.add-on` and `add-on.json` on file changes.
+
 ### Publishing Tips
 
 - Keep add-on source in git (not just compiled output).

packages/cli/src/cli.ts

@@ -9,6 +9,7 @@ import {
   SUPPORTED_PACKAGE_MANAGERS,
   addToApp,
   compileAddOn,
+  devAddOn,
   compileStarter,
   createApp,
   createSerializedOptions,
@@ -697,6 +698,14 @@ Remove your node_modules directory and package lock file and re-install.`,
     .action(async () => {
       await compileAddOn(environment)
     })
+  addOnCommand
+    .command('dev')
+    .description(
+      'Watch project files and continuously refresh .add-on and add-on.json',
+    )
+    .action(async () => {
+      await devAddOn(environment)
+    })
 
   // === STARTER SUBCOMMAND ===
   const starterCommand = program.command('starter')

packages/create/src/custom-add-ons/add-on.ts

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises'
+import { readFile, watch } from 'node:fs/promises'
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { basename, dirname, resolve } from 'node:path'
 
@@ -36,6 +36,22 @@ const COMPILED_FILE = 'add-on.json'
 
 const ASSETS_DIR = 'assets'
 
+const ADD_ON_DEV_IGNORE_PREFIXES = [
+  '.add-on/',
+  '.git/',
+  'node_modules/',
+  '.turbo/',
+  'dist/',
+]
+
+function shouldIgnoreDevPath(path: string) {
+  const normalized = path.replace(/\\/g, '/')
+  if (normalized === COMPILED_FILE) return true
+  return ADD_ON_DEV_IGNORE_PREFIXES.some((prefix) =>
+    normalized.startsWith(prefix),
+  )
+}
+
 export function camelCase(str: string) {
   return str
     .split(/(\.|-|\/)/)
@@ -218,6 +234,56 @@ export async function initAddOn(environment: Environment) {
   await compileAddOn(environment)
 }
 
+export async function devAddOn(environment: Environment) {
+  await initAddOn(environment)
+
+  environment.info(
+    'Add-on dev mode is running.',
+    'Watching project files and recompiling add-on output on changes. Press Ctrl+C to stop.',
+  )
+
+  const abortController = new AbortController()
+  let debounceTimeout: ReturnType<typeof setTimeout> | undefined
+
+  const rerun = async () => {
+    try {
+      await updateAddOnInfo(environment)
+      await compileAddOn(environment)
+      environment.info('Add-on updated.', 'Compiled add-on.json and refreshed .add-on')
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      environment.error('Failed to rebuild add-on.', message)
+    }
+  }
+
+  process.once('SIGINT', () => {
+    abortController.abort()
+  })
+
+  try {
+    for await (const event of watch(process.cwd(), {
+      recursive: true,
+      signal: abortController.signal,
+    })) {
+      const file = event.filename?.toString()
+      if (!file || shouldIgnoreDevPath(file)) continue
+
+      if (debounceTimeout) {
+        clearTimeout(debounceTimeout)
+      }
+
+      debounceTimeout = setTimeout(() => {
+        void rerun()
+      }, 200)
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (!message.includes('aborted')) {
+      throw error
+    }
+  }
+}
+
 export async function loadRemoteAddOn(url: string): Promise<AddOn> {
   const response = await fetch(url)
   const jsonContent = await response.json()

packages/create/src/index.ts

@@ -61,7 +61,7 @@ export {
 export { formatCommand, handleSpecialURL } from './utils.js'
 
 export { initStarter, compileStarter } from './custom-add-ons/starter.js'
-export { initAddOn, compileAddOn } from './custom-add-ons/add-on.js'
+export { initAddOn, compileAddOn, devAddOn } from './custom-add-ons/add-on.js'
 export {
   createAppOptionsFromPersisted,
   createSerializedOptionsFromPersisted,