@tanstack/cli 0.59.6 → 0.59.7

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @tanstack/cli
 
+## 0.59.7
+
+### Patch Changes
+
+- Add a continuous development workflow for custom add-on authors. ([`b3cc585`](https://github.com/TanStack/cli/commit/b3cc5851d2b81613e3b024eb7981c440ee5183af))
+
+  - Add `tanstack add-on dev` to watch project files and continuously refresh `.add-on` outputs.
+  - Rebuild `.add-on` assets and `add-on.json` automatically when source files change.
+  - Document the new add-on development loop in the custom add-on guide.
+
+- Improve scaffold customization and custom add-on authoring flow. ([`5fbf262`](https://github.com/TanStack/cli/commit/5fbf262fe3a0d070e6a78fa2f2a920b176b84480))
+
+  - Add `--examples` / `--no-examples` support to include or omit demo/example pages during app creation.
+  - Prompt for add-on-declared environment variables during interactive create and seed entered values into generated `.env.local`.
+  - Ensure custom add-on/starter metadata consistently includes a `version`, with safe backfill for older metadata files.
+  - Align bundled starter/example metadata and docs with current Start/file-router behavior.
+
+- Updated dependencies [[`b3cc585`](https://github.com/TanStack/cli/commit/b3cc5851d2b81613e3b024eb7981c440ee5183af), [`5fbf262`](https://github.com/TanStack/cli/commit/5fbf262fe3a0d070e6a78fa2f2a920b176b84480)]:
+  - @tanstack/create@0.61.5
+  - @tanstack/create-ui@0.59.7
+
 ## 0.59.6
 
 ### Patch Changes

package/dist/cli.js

@@ -4,7 +4,7 @@ import { Command, InvalidArgumentError } from 'commander';
 import { cancel, confirm, intro, isCancel, log } from '@clack/prompts';
 import chalk from 'chalk';
 import semver from 'semver';
-import { SUPPORTED_PACKAGE_MANAGERS, addToApp, compileAddOn, compileStarter, createApp, createSerializedOptions, getAllAddOns, getFrameworkByName, getFrameworks, initAddOn, initStarter, } from '@tanstack/create';
+import { SUPPORTED_PACKAGE_MANAGERS, addToApp, compileAddOn, devAddOn, compileStarter, createApp, createSerializedOptions, getAllAddOns, getFrameworkByName, getFrameworks, initAddOn, initStarter, } from '@tanstack/create';
 import { launchUI } from '@tanstack/create-ui';
 import { runMCPServer } from './mcp.js';
 import { promptForAddOns, promptForCreateOptions } from './options.js';
@@ -300,7 +300,9 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
             .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')
-            .option('--no-tailwind', 'Deprecated: compatibility flag; Tailwind opt-out is ignored');
+            .option('--no-tailwind', 'Deprecated: compatibility flag; Tailwind opt-out is ignored')
+            .option('--examples', 'include demo/example pages')
+            .option('--no-examples', 'exclude demo/example pages');
         if (deployments.size > 0) {
             cmd.option(`--deployment <${Array.from(deployments).join('|')}>`, `Explicitly tell the CLI to use this deployment adapter`, (value) => {
                 if (!deployments.has(value)) {
@@ -473,6 +475,12 @@ 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');
     starterCommand

package/dist/command-line.js

@@ -123,7 +123,11 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
         }
         return [];
     }
-    const chosenAddOns = await selectAddOns();
+    const includeExamples = cliOptions.examples ?? !routerOnly;
+    const chosenAddOnsRaw = await selectAddOns();
+    const chosenAddOns = includeExamples
+        ? chosenAddOnsRaw
+        : chosenAddOnsRaw.filter((addOn) => addOn.type !== 'example');
     // Handle add-on configuration option
     let addOnOptionsFromCLI = {};
     if (cliOptions.addOnConfig) {
@@ -135,7 +139,7 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
             process.exit(1);
         }
     }
-    return {
+    const normalized = {
         projectName: projectName,
         targetDir,
         framework,
@@ -154,6 +158,11 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
         },
         starter: starter,
     };
+    normalized.includeExamples =
+        includeExamples;
+    normalized.envVarValues =
+        {};
+    return normalized;
 }
 export function validateDevWatchOptions(cliOptions) {
     if (!cliOptions.devWatch) {

package/dist/options.js

@@ -1,6 +1,6 @@
 import { intro } from '@clack/prompts';
 import { finalizeAddOns, getFrameworkById, getPackageManager, populateAddOnOptionsDefaults, readConfigFile, } from '@tanstack/create';
-import { getProjectName, promptForAddOnOptions, selectAddOns, selectDeployment, selectGit, selectPackageManager, selectToolchain, } from './ui-prompts.js';
+import { getProjectName, promptForAddOnOptions, promptForEnvVars, selectAddOns, selectDeployment, selectExamples, selectGit, selectPackageManager, selectToolchain, } from './ui-prompts.js';
 import { getCurrentDirectoryName, sanitizePackageName, validateProjectName, } from './utils.js';
 export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], showDeploymentOptions = false, }) {
     const options = {};
@@ -48,6 +48,10 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], sh
         : undefined;
     // Add-ons selection
     const addOns = new Set();
+    // Examples/demo pages are enabled by default
+    const includeExamples = cliOptions.examples ?? (routerOnly ? false : await selectExamples());
+    options.includeExamples =
+        includeExamples;
     if (toolchain) {
         addOns.add(toolchain);
     }
@@ -71,11 +75,16 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], sh
         for (const addOn of await selectAddOns(options.framework, options.mode, 'add-on', 'What add-ons would you like for your project?', forcedAddOns)) {
             addOns.add(addOn);
         }
-        for (const addOn of await selectAddOns(options.framework, options.mode, 'example', 'Would you like an example?', forcedAddOns, false)) {
-            addOns.add(addOn);
+        if (includeExamples) {
+            for (const addOn of await selectAddOns(options.framework, options.mode, 'example', 'Would you like an example?', forcedAddOns, false)) {
+                addOns.add(addOn);
+            }
         }
     }
-    options.chosenAddOns = Array.from(await finalizeAddOns(options.framework, options.mode, Array.from(addOns)));
+    const chosenAddOns = Array.from(await finalizeAddOns(options.framework, options.mode, Array.from(addOns)));
+    options.chosenAddOns = includeExamples
+        ? chosenAddOns
+        : chosenAddOns.filter((addOn) => addOn.type !== 'example');
     // Tailwind is always enabled
     options.tailwind = true;
     // Prompt for add-on options in interactive mode
@@ -90,6 +99,12 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], sh
         // Merge user options with defaults
         options.addOnOptions = { ...defaultOptions, ...userOptions };
     }
+    // Prompt for env vars exposed by selected add-ons in interactive mode
+    const envVarValues = Array.isArray(cliOptions.addOns)
+        ? {}
+        : await promptForEnvVars(options.chosenAddOns);
+    options.envVarValues =
+        envVarValues;
     options.git = cliOptions.git ?? (await selectGit());
     if (cliOptions.install === false) {
         options.install = false;

package/dist/types/types.d.ts

@@ -22,4 +22,5 @@ export interface CliOptions {
     routerOnly?: boolean;
     template?: string;
     tailwind?: boolean;
+    examples?: boolean;
 }

package/dist/types/ui-prompts.d.ts

@@ -1,9 +1,11 @@
-import type { PackageManager } from '@tanstack/create';
+import type { AddOn, PackageManager } from '@tanstack/create';
 import type { Framework } from '@tanstack/create/dist/types/types.js';
 export declare function getProjectName(): Promise<string>;
 export declare function selectPackageManager(): Promise<PackageManager>;
 export declare function selectAddOns(framework: Framework, mode: string, type: string, message: string, forcedAddOns?: Array<string>, allowMultiple?: boolean): Promise<Array<string>>;
 export declare function selectGit(): Promise<boolean>;
+export declare function selectExamples(): Promise<boolean>;
 export declare function selectToolchain(framework: Framework, toolchain?: string | false): Promise<string | undefined>;
 export declare function promptForAddOnOptions(addOnIds: Array<string>, framework: Framework): Promise<Record<string, Record<string, any>>>;
+export declare function promptForEnvVars(addOns: Array<AddOn>): Promise<Record<string, string>>;
 export declare function selectDeployment(framework: Framework, deployment?: string): Promise<string | undefined>;

package/dist/ui-prompts.js

@@ -1,4 +1,4 @@
-import { cancel, confirm, isCancel, multiselect, note, select, text, } from '@clack/prompts';
+import { cancel, confirm, isCancel, multiselect, note, password, select, text, } from '@clack/prompts';
 import { DEFAULT_PACKAGE_MANAGER, SUPPORTED_PACKAGE_MANAGERS, getAllAddOns, } from '@tanstack/create';
 import { validateProjectName } from './utils.js';
 export async function getProjectName() {
@@ -106,6 +106,17 @@ export async function selectGit() {
     }
     return git;
 }
+export async function selectExamples() {
+    const includeExamples = await confirm({
+        message: 'Would you like to include demo/example pages?',
+        initialValue: true,
+    });
+    if (isCancel(includeExamples)) {
+        cancel('Operation cancelled.');
+        process.exit(0);
+    }
+    return includeExamples;
+}
 export async function selectToolchain(framework, toolchain) {
     if (toolchain === false) {
         return undefined;
@@ -170,6 +181,48 @@ export async function promptForAddOnOptions(addOnIds, framework) {
     }
     return addOnOptions;
 }
+export async function promptForEnvVars(addOns) {
+    const envVars = new Map();
+    for (const addOn of addOns) {
+        for (const envVar of addOn.envVars || []) {
+            if (!envVars.has(envVar.name)) {
+                envVars.set(envVar.name, envVar);
+            }
+        }
+    }
+    const result = {};
+    for (const envVar of envVars.values()) {
+        const label = envVar.description
+            ? `${envVar.name} (${envVar.description})`
+            : envVar.name;
+        const value = envVar.secret
+            ? await password({
+                message: `Enter ${label}`,
+                validate: envVar.required
+                    ? (v) => v && v.trim().length > 0
+                        ? undefined
+                        : `${envVar.name} is required`
+                    : undefined,
+            })
+            : await text({
+                message: `Enter ${label}`,
+                defaultValue: envVar.default,
+                validate: envVar.required
+                    ? (v) => v && v.trim().length > 0
+                        ? undefined
+                        : `${envVar.name} is required`
+                    : undefined,
+            });
+        if (isCancel(value)) {
+            cancel('Operation cancelled.');
+            process.exit(0);
+        }
+        if (value && value.trim()) {
+            result[envVar.name] = value.trim();
+        }
+    }
+    return result;
+}
 export async function selectDeployment(framework, deployment) {
     const deployments = new Set();
     let initialValue = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/cli",
-  "version": "0.59.6",
+  "version": "0.59.7",
   "description": "TanStack CLI",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,8 +38,8 @@
     "tempy": "^3.1.0",
     "validate-npm-package-name": "^7.0.0",
     "zod": "^3.24.2",
-    "@tanstack/create": "0.61.4",
-    "@tanstack/create-ui": "0.59.6"
+    "@tanstack/create": "0.61.5",
+    "@tanstack/create-ui": "0.59.7"
   },
   "devDependencies": {
     "@tanstack/config": "^0.16.2",

package/src/cli.ts

@@ -9,6 +9,7 @@ import {
   SUPPORTED_PACKAGE_MANAGERS,
   addToApp,
   compileAddOn,
+  devAddOn,
   compileStarter,
   createApp,
   createSerializedOptions,
@@ -466,6 +467,8 @@ export function cli({
         '--no-tailwind',
         'Deprecated: compatibility flag; Tailwind opt-out is ignored',
       )
+      .option('--examples', 'include demo/example pages')
+      .option('--no-examples', 'exclude demo/example pages')
 
     if (deployments.size > 0) {
       cmd.option<string>(
@@ -695,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')

package/src/command-line.ts

@@ -191,7 +191,11 @@ export async function normalizeOptions(
     return []
   }
 
-  const chosenAddOns = await selectAddOns()
+  const includeExamples = cliOptions.examples ?? !routerOnly
+  const chosenAddOnsRaw = await selectAddOns()
+  const chosenAddOns = includeExamples
+    ? chosenAddOnsRaw
+    : chosenAddOnsRaw.filter((addOn) => addOn.type !== 'example')
 
   // Handle add-on configuration option
   let addOnOptionsFromCLI = {}
@@ -204,7 +208,7 @@ export async function normalizeOptions(
     }
   }
 
-  return {
+  const normalized = {
     projectName: projectName,
     targetDir,
     framework,
@@ -224,6 +228,13 @@ export async function normalizeOptions(
     },
     starter: starter,
   }
+
+  ;(normalized as Options & { includeExamples?: boolean }).includeExamples =
+    includeExamples
+  ;(normalized as Options & { envVarValues?: Record<string, string> }).envVarValues =
+    {}
+
+  return normalized
 }
 
 export function validateDevWatchOptions(cliOptions: CliOptions): {

package/src/options.ts

@@ -11,8 +11,10 @@ import {
 import {
   getProjectName,
   promptForAddOnOptions,
+  promptForEnvVars,
   selectAddOns,
   selectDeployment,
+  selectExamples,
   selectGit,
   selectPackageManager,
   selectToolchain,
@@ -92,6 +94,12 @@ export async function promptForCreateOptions(
   // Add-ons selection
   const addOns: Set<string> = new Set()
 
+  // Examples/demo pages are enabled by default
+  const includeExamples =
+    cliOptions.examples ?? (routerOnly ? false : await selectExamples())
+  ;(options as Required<Options> & { includeExamples?: boolean }).includeExamples =
+    includeExamples
+
   if (toolchain) {
     addOns.add(toolchain)
   }
@@ -123,21 +131,26 @@ export async function promptForCreateOptions(
       addOns.add(addOn)
     }
 
-    for (const addOn of await selectAddOns(
-      options.framework,
-      options.mode,
-      'example',
-      'Would you like an example?',
-      forcedAddOns,
-      false,
-    )) {
-      addOns.add(addOn)
+    if (includeExamples) {
+      for (const addOn of await selectAddOns(
+        options.framework,
+        options.mode,
+        'example',
+        'Would you like an example?',
+        forcedAddOns,
+        false,
+      )) {
+        addOns.add(addOn)
+      }
     }
   }
 
-  options.chosenAddOns = Array.from(
+  const chosenAddOns = Array.from(
     await finalizeAddOns(options.framework, options.mode, Array.from(addOns)),
   )
+  options.chosenAddOns = includeExamples
+    ? chosenAddOns
+    : chosenAddOns.filter((addOn) => addOn.type !== 'example')
 
   // Tailwind is always enabled
   options.tailwind = true
@@ -157,6 +170,13 @@ export async function promptForCreateOptions(
     options.addOnOptions = { ...defaultOptions, ...userOptions }
   }
 
+  // Prompt for env vars exposed by selected add-ons in interactive mode
+  const envVarValues = Array.isArray(cliOptions.addOns)
+    ? {}
+    : await promptForEnvVars(options.chosenAddOns)
+  ;(options as Required<Options> & { envVarValues?: Record<string, string> }).envVarValues =
+    envVarValues
+
   options.git = cliOptions.git ?? (await selectGit())
   if (cliOptions.install === false) {
     options.install = false

package/src/types.ts

@@ -23,4 +23,5 @@ export interface CliOptions {
   routerOnly?: boolean
   template?: string
   tailwind?: boolean
+  examples?: boolean
 }

package/src/ui-prompts.ts

@@ -4,6 +4,7 @@ import {
   isCancel,
   multiselect,
   note,
+  password,
   select,
   text,
 } from '@clack/prompts'
@@ -151,6 +152,18 @@ export async function selectGit(): Promise<boolean> {
   return git
 }
 
+export async function selectExamples(): Promise<boolean> {
+  const includeExamples = await confirm({
+    message: 'Would you like to include demo/example pages?',
+    initialValue: true,
+  })
+  if (isCancel(includeExamples)) {
+    cancel('Operation cancelled.')
+    process.exit(0)
+  }
+  return includeExamples
+}
+
 export async function selectToolchain(
   framework: Framework,
   toolchain?: string | false,
@@ -239,6 +252,69 @@ export async function promptForAddOnOptions(
   return addOnOptions
 }
 
+export async function promptForEnvVars(
+  addOns: Array<AddOn>,
+): Promise<Record<string, string>> {
+  const envVars = new Map<
+    string,
+    {
+      name: string
+      description?: string
+      required?: boolean
+      default?: string
+      secret?: boolean
+    }
+  >()
+
+  for (const addOn of addOns as Array<any>) {
+    for (const envVar of addOn.envVars || []) {
+      if (!envVars.has(envVar.name)) {
+        envVars.set(envVar.name, envVar)
+      }
+    }
+  }
+
+  const result: Record<string, string> = {}
+
+  for (const envVar of envVars.values()) {
+    const label = envVar.description
+      ? `${envVar.name} (${envVar.description})`
+      : envVar.name
+
+    const value = envVar.secret
+      ? await password({
+          message: `Enter ${label}`,
+          validate: envVar.required
+            ? (v) =>
+                v && v.trim().length > 0
+                  ? undefined
+                  : `${envVar.name} is required`
+            : undefined,
+        })
+      : await text({
+          message: `Enter ${label}`,
+          defaultValue: envVar.default,
+          validate: envVar.required
+            ? (v) =>
+                v && v.trim().length > 0
+                  ? undefined
+                  : `${envVar.name} is required`
+            : undefined,
+        })
+
+    if (isCancel(value)) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+
+    if (value && value.trim()) {
+      result[envVar.name] = value.trim()
+    }
+  }
+
+  return result
+}
+
 export async function selectDeployment(
   framework: Framework,
   deployment?: string,

package/tests/command-line.test.ts

@@ -300,6 +300,23 @@ describe('normalizeOptions', () => {
     expect(options?.mode).toBe('file-router')
   })
 
+  it('includes examples by default in non-router-only mode', async () => {
+    const options = await normalizeOptions({
+      projectName: 'test',
+    })
+
+    expect((options as any)?.includeExamples).toBe(true)
+  })
+
+  it('supports disabling examples from the CLI', async () => {
+    const options = await normalizeOptions({
+      projectName: 'test',
+      examples: false,
+    })
+
+    expect((options as any)?.includeExamples).toBe(false)
+  })
+
   it('should ignore add-ons and deployment in router-only mode but keep toolchain', async () => {
     __testRegisterFramework({
       id: 'react-cra',