@tanstack/cli 0.59.5 → 0.59.7

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @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
+
+- Improve CLI compatibility and scaffold behavior for legacy router-first workflows. ([`2949819`](https://github.com/TanStack/cli/commit/2949819058b4d4b1760be683ef29bfd459ddb28b))
+
+  - Add safer target directory handling by warning before creating into non-empty folders.
+  - Support explicit git initialization control via `--git` and `--no-git`.
+  - Restore router-only compatibility mode with file-based routing templates (without Start-dependent add-ons/deployments/starters), while still allowing toolchains.
+  - Default `create-tsrouter-app` to router-only compatibility mode.
+  - Remove stale `count.txt` ignore entries from base templates.
+
+  Also expands starter documentation with clearer creation, maintenance, UI usage, and banner guidance.
+
+- Updated dependencies [[`164522e`](https://github.com/TanStack/cli/commit/164522e444188e83710fc599304132de8cb379e6), [`2949819`](https://github.com/TanStack/cli/commit/2949819058b4d4b1760be683ef29bfd459ddb28b)]:
+  - @tanstack/create@0.61.4
+  - @tanstack/create-ui@0.59.6
+
 ## 0.59.5
 
 ### Patch Changes

package/dist/cli.js

@@ -1,10 +1,10 @@
 import fs from 'node:fs';
 import { resolve } from 'node:path';
 import { Command, InvalidArgumentError } from 'commander';
-import { intro, log } from '@clack/prompts';
+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';
@@ -15,9 +15,31 @@ import { DevWatchManager } from './dev-watch.js';
 const packageJsonPath = new URL('../package.json', import.meta.url);
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
 const VERSION = packageJson.version;
-export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaultFramework, webBase, frameworkDefinitionInitializers, showDeploymentOptions = false, legacyAutoCreate = false, }) {
+export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaultFramework, webBase, frameworkDefinitionInitializers, showDeploymentOptions = false, legacyAutoCreate = false, defaultRouterOnly = false, }) {
     const environment = createUIEnvironment(appName, false);
     const program = new Command();
+    async function confirmTargetDirectorySafety(targetDir, forced) {
+        if (forced) {
+            return;
+        }
+        if (!fs.existsSync(targetDir)) {
+            return;
+        }
+        if (!fs.statSync(targetDir).isDirectory()) {
+            throw new Error(`Target path exists and is not a directory: ${targetDir}`);
+        }
+        if (fs.readdirSync(targetDir).length === 0) {
+            return;
+        }
+        const shouldContinue = await confirm({
+            message: `Target directory "${targetDir}" already exists and is not empty. Continue anyway?`,
+            initialValue: false,
+        });
+        if (isCancel(shouldContinue) || !shouldContinue) {
+            cancel('Operation cancelled.');
+            process.exit(0);
+        }
+    }
     const availableFrameworks = getFrameworks().map((f) => f.name);
     const toolchains = new Set();
     for (const framework of getFrameworks()) {
@@ -158,6 +180,7 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
                 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
@@ -178,6 +201,14 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
                 projectName,
                 ...options,
             };
+            if (defaultRouterOnly && cliOptions.routerOnly === undefined) {
+                cliOptions.routerOnly = true;
+            }
+            if (cliOptions.routerOnly !== true &&
+                cliOptions.template &&
+                cliOptions.template.toLowerCase() !== 'file-router') {
+                cliOptions.routerOnly = true;
+            }
             cliOptions.framework = getFrameworkByName(options.framework || defaultFramework || 'React').id;
             let finalOptions;
             if (cliOptions.interactive || cliOptions.addOns === true) {
@@ -217,6 +248,9 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
             if (!finalOptions) {
                 throw new Error('No options were provided');
             }
+            ;
+            finalOptions.routerOnly =
+                !!cliOptions.routerOnly;
             // Determine target directory:
             // 1. Use --target-dir if provided
             // 2. Use targetDir from normalizeOptions if set (handles "." case)
@@ -234,6 +268,7 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
             else {
                 finalOptions.targetDir = resolve(process.cwd(), finalOptions.projectName);
             }
+            await confirmTargetDirectorySafety(finalOptions.targetDir, options.force);
             await createApp(environment, finalOptions);
         }
         catch (error) {
@@ -262,10 +297,12 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
             return value;
         })
             .option('--dev-watch <path>', 'Watch a framework directory for changes and auto-rebuild')
-            .option('--router-only', 'Deprecated: compatibility flag from create-tsrouter-app')
+            .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)) {
@@ -295,6 +332,7 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
         })
             .option('--list-add-ons', 'list all available add-ons', false)
             .option('--addon-details <addon-id>', 'show detailed information about a specific add-on')
+            .option('--git', 'create a git repository')
             .option('--no-git', 'do not create a git repository')
             .option('--target-dir <path>', 'the target directory for the application root')
             .option('--ui', 'Launch the UI for project creation')
@@ -437,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

@@ -10,7 +10,16 @@ const SUPPORTED_LEGACY_TEMPLATES = new Set([
 export function validateLegacyCreateFlags(cliOptions) {
     const warnings = [];
     if (cliOptions.routerOnly) {
-        warnings.push('The --router-only flag is deprecated and ignored. `tanstack create` already creates router-based apps.');
+        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.');
+    }
+    if (cliOptions.routerOnly && cliOptions.addOns) {
+        warnings.push('Ignoring --add-ons in router-only compatibility mode.');
+    }
+    if (cliOptions.routerOnly && cliOptions.deployment) {
+        warnings.push('Ignoring --deployment in router-only compatibility mode.');
+    }
+    if (cliOptions.routerOnly && cliOptions.starter) {
+        warnings.push('Ignoring --starter in router-only compatibility mode.');
     }
     if (cliOptions.tailwind === true) {
         warnings.push('The --tailwind flag is deprecated and ignored. Tailwind is always enabled in TanStack Start scaffolds.');
@@ -34,7 +43,7 @@ export function validateLegacyCreateFlags(cliOptions) {
             error: `Invalid --template value: ${cliOptions.template}. Supported values are: file-router, typescript, tsx.`,
         };
     }
-    warnings.push('The --template flag is deprecated. TypeScript/TSX is the default and only supported template.');
+    warnings.push('The --template flag is deprecated and mapped for compatibility.');
     return { warnings };
 }
 export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
@@ -60,7 +69,12 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
     }
     // Mode is always file-router (TanStack Start)
     let mode = 'file-router';
-    const starter = cliOptions.starter
+    let routerOnly = !!cliOptions.routerOnly;
+    const template = cliOptions.template?.toLowerCase().trim();
+    if (template && template !== 'file-router') {
+        routerOnly = true;
+    }
+    const starter = !routerOnly && cliOptions.starter
         ? await loadStarter(cliOptions.starter)
         : undefined;
     // TypeScript and Tailwind are always enabled with TanStack Start
@@ -85,10 +99,10 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
             cliOptions.toolchain ||
             cliOptions.deployment) {
             const selectedAddOns = new Set([
-                ...(starter?.dependsOn || []),
-                ...(forcedAddOns || []),
+                ...(routerOnly ? [] : (starter?.dependsOn || [])),
+                ...(routerOnly ? [] : (forcedAddOns || [])),
             ]);
-            if (cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
+            if (!routerOnly && cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
                 for (const a of cliOptions.addOns) {
                     if (a.toLowerCase() === 'start') {
                         continue;
@@ -99,17 +113,21 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
             if (cliOptions.toolchain) {
                 selectedAddOns.add(cliOptions.toolchain);
             }
-            if (cliOptions.deployment) {
+            if (!routerOnly && cliOptions.deployment) {
                 selectedAddOns.add(cliOptions.deployment);
             }
-            if (!cliOptions.deployment && opts?.forcedDeployment) {
+            if (!routerOnly && !cliOptions.deployment && opts?.forcedDeployment) {
                 selectedAddOns.add(opts.forcedDeployment);
             }
             return await finalizeAddOns(framework, mode, Array.from(selectedAddOns));
         }
         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) {
@@ -121,7 +139,7 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
             process.exit(1);
         }
     }
-    return {
+    const normalized = {
         projectName: projectName,
         targetDir,
         framework,
@@ -131,7 +149,7 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
         packageManager: cliOptions.packageManager ||
             getPackageManager() ||
             DEFAULT_PACKAGE_MANAGER,
-        git: !!cliOptions.git,
+        git: cliOptions.git ?? true,
         install: cliOptions.install,
         chosenAddOns,
         addOnOptions: {
@@ -140,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,7 +1,6 @@
-import fs from 'node:fs';
-import { cancel, confirm, intro, isCancel } from '@clack/prompts';
+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 = {};
@@ -24,21 +23,10 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], sh
     else {
         options.projectName = await getProjectName();
     }
-    // Check if target directory is empty
-    if (!cliOptions.force &&
-        fs.existsSync(options.projectName) &&
-        fs.readdirSync(options.projectName).length > 0) {
-        const shouldContinue = await confirm({
-            message: `Target directory ${options.projectName} is not empty. Do you want to continue?`,
-            initialValue: true,
-        });
-        if (isCancel(shouldContinue) || !shouldContinue) {
-            cancel('Operation cancelled.');
-            process.exit(0);
-        }
-    }
     // Mode is always file-router (TanStack Start)
     options.mode = 'file-router';
+    const template = cliOptions.template?.toLowerCase().trim();
+    const routerOnly = !!cliOptions.routerOnly || (template ? template !== 'file-router' : false);
     // TypeScript is always enabled with file-router
     options.typescript = true;
     // Package manager selection
@@ -54,20 +42,28 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], sh
     const toolchain = await selectToolchain(options.framework, cliOptions.toolchain);
     // Deployment selection
     const deployment = showDeploymentOptions
-        ? await selectDeployment(options.framework, cliOptions.deployment)
+        ? routerOnly
+            ? undefined
+            : await selectDeployment(options.framework, cliOptions.deployment)
         : 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);
     }
     if (deployment) {
         addOns.add(deployment);
     }
-    for (const addOn of forcedAddOns) {
-        addOns.add(addOn);
+    if (!routerOnly) {
+        for (const addOn of forcedAddOns) {
+            addOns.add(addOn);
+        }
     }
-    if (Array.isArray(cliOptions.addOns)) {
+    if (!routerOnly && Array.isArray(cliOptions.addOns)) {
         for (const addOn of cliOptions.addOns) {
             if (addOn.toLowerCase() === 'start') {
                 continue;
@@ -75,15 +71,20 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], sh
             addOns.add(addOn);
         }
     }
-    else {
+    else if (!routerOnly) {
         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
@@ -98,7 +99,13 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], sh
         // Merge user options with defaults
         options.addOnOptions = { ...defaultOptions, ...userOptions };
     }
-    options.git = cliOptions.git || (await selectGit());
+    // 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/cli.d.ts

@@ -1,5 +1,5 @@
 import type { FrameworkDefinition } from '@tanstack/create';
-export declare function cli({ name, appName, forcedAddOns, forcedDeployment, defaultFramework, webBase, frameworkDefinitionInitializers, showDeploymentOptions, legacyAutoCreate, }: {
+export declare function cli({ name, appName, forcedAddOns, forcedDeployment, defaultFramework, webBase, frameworkDefinitionInitializers, showDeploymentOptions, legacyAutoCreate, defaultRouterOnly, }: {
     name: string;
     appName: string;
     forcedAddOns?: Array<string>;
@@ -9,4 +9,5 @@ export declare function cli({ name, appName, forcedAddOns, forcedDeployment, def
     frameworkDefinitionInitializers?: Array<() => FrameworkDefinition>;
     showDeploymentOptions?: boolean;
     legacyAutoCreate?: boolean;
+    defaultRouterOnly?: boolean;
 }): void;

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.5",
+  "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.3",
-    "@tanstack/create-ui": "0.59.5"
+    "@tanstack/create": "0.61.5",
+    "@tanstack/create-ui": "0.59.7"
   },
   "devDependencies": {
     "@tanstack/config": "^0.16.2",

package/src/cli.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import { resolve } from 'node:path'
 import { Command, InvalidArgumentError } from 'commander'
-import { intro, log } from '@clack/prompts'
+import { cancel, confirm, intro, isCancel, log } from '@clack/prompts'
 import chalk from 'chalk'
 import semver from 'semver'
 
@@ -9,6 +9,7 @@ import {
   SUPPORTED_PACKAGE_MANAGERS,
   addToApp,
   compileAddOn,
+  devAddOn,
   compileStarter,
   createApp,
   createSerializedOptions,
@@ -55,6 +56,7 @@ export function cli({
   frameworkDefinitionInitializers,
   showDeploymentOptions = false,
   legacyAutoCreate = false,
+  defaultRouterOnly = false,
 }: {
   name: string
   appName: string
@@ -65,11 +67,43 @@ export function cli({
   frameworkDefinitionInitializers?: Array<() => FrameworkDefinition>
   showDeploymentOptions?: boolean
   legacyAutoCreate?: boolean
+  defaultRouterOnly?: boolean
 }) {
   const environment = createUIEnvironment(appName, false)
 
   const program = new Command()
 
+  async function confirmTargetDirectorySafety(
+    targetDir: string,
+    forced?: boolean,
+  ) {
+    if (forced) {
+      return
+    }
+
+    if (!fs.existsSync(targetDir)) {
+      return
+    }
+
+    if (!fs.statSync(targetDir).isDirectory()) {
+      throw new Error(`Target path exists and is not a directory: ${targetDir}`)
+    }
+
+    if (fs.readdirSync(targetDir).length === 0) {
+      return
+    }
+
+    const shouldContinue = await confirm({
+      message: `Target directory "${targetDir}" already exists and is not empty. Continue anyway?`,
+      initialValue: false,
+    })
+
+    if (isCancel(shouldContinue) || !shouldContinue) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+  }
+
   const availableFrameworks = getFrameworks().map((f) => f.name)
 
   const toolchains = new Set<string>()
@@ -251,6 +285,7 @@ export function cli({
         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`)
 
@@ -275,6 +310,18 @@ export function cli({
         ...options,
       } as CliOptions
 
+      if (defaultRouterOnly && cliOptions.routerOnly === undefined) {
+        cliOptions.routerOnly = true
+      }
+
+      if (
+        cliOptions.routerOnly !== true &&
+        cliOptions.template &&
+        cliOptions.template.toLowerCase() !== 'file-router'
+      ) {
+        cliOptions.routerOnly = true
+      }
+
       cliOptions.framework = getFrameworkByName(
         options.framework || defaultFramework || 'React',
       )!.id
@@ -327,6 +374,9 @@ export function cli({
         throw new Error('No options were provided')
       }
 
+      ;(finalOptions as Options & { routerOnly?: boolean }).routerOnly =
+        !!cliOptions.routerOnly
+
       // Determine target directory:
       // 1. Use --target-dir if provided
       // 2. Use targetDir from normalizeOptions if set (handles "." case)
@@ -342,6 +392,7 @@ export function cli({
         finalOptions.targetDir = resolve(process.cwd(), finalOptions.projectName)
       }
 
+      await confirmTargetDirectorySafety(finalOptions.targetDir, options.force)
       await createApp(environment, finalOptions)
     } catch (error) {
       log.error(
@@ -402,7 +453,7 @@ export function cli({
       )
       .option(
         '--router-only',
-        'Deprecated: compatibility flag from create-tsrouter-app',
+        'Use router-only compatibility mode (file-based routing without TanStack Start)',
       )
       .option(
         '--template <type>',
@@ -416,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>(
@@ -471,6 +524,7 @@ export function cli({
         '--addon-details <addon-id>',
         'show detailed information about a specific add-on',
       )
+      .option('--git', 'create a git repository')
       .option('--no-git', 'do not create a git repository')
       .option(
         '--target-dir <path>',
@@ -644,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

@@ -33,10 +33,26 @@ export function validateLegacyCreateFlags(cliOptions: CliOptions): {
 
   if (cliOptions.routerOnly) {
     warnings.push(
-      'The --router-only flag is deprecated and ignored. `tanstack create` already creates router-based apps.',
+      '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.',
     )
   }
 
+  if (cliOptions.routerOnly && cliOptions.addOns) {
+    warnings.push(
+      'Ignoring --add-ons in router-only compatibility mode.',
+    )
+  }
+
+  if (cliOptions.routerOnly && cliOptions.deployment) {
+    warnings.push(
+      'Ignoring --deployment in router-only compatibility mode.',
+    )
+  }
+
+  if (cliOptions.routerOnly && cliOptions.starter) {
+    warnings.push('Ignoring --starter in router-only compatibility mode.')
+  }
+
   if (cliOptions.tailwind === true) {
     warnings.push(
       'The --tailwind flag is deprecated and ignored. Tailwind is always enabled in TanStack Start scaffolds.',
@@ -70,9 +86,7 @@ export function validateLegacyCreateFlags(cliOptions: CliOptions): {
     }
   }
 
-  warnings.push(
-    'The --template flag is deprecated. TypeScript/TSX is the default and only supported template.',
-  )
+  warnings.push('The --template flag is deprecated and mapped for compatibility.')
 
   return { warnings }
 }
@@ -110,8 +124,14 @@ export async function normalizeOptions(
 
   // Mode is always file-router (TanStack Start)
   let mode = 'file-router'
+  let routerOnly = !!cliOptions.routerOnly
 
-  const starter = cliOptions.starter
+  const template = cliOptions.template?.toLowerCase().trim()
+  if (template && template !== 'file-router') {
+    routerOnly = true
+  }
+
+  const starter = !routerOnly && cliOptions.starter
     ? await loadStarter(cliOptions.starter)
     : undefined
 
@@ -143,10 +163,10 @@ export async function normalizeOptions(
       cliOptions.deployment
     ) {
       const selectedAddOns = new Set<string>([
-        ...(starter?.dependsOn || []),
-        ...(forcedAddOns || []),
+        ...(routerOnly ? [] : (starter?.dependsOn || [])),
+        ...(routerOnly ? [] : (forcedAddOns || [])),
       ])
-      if (cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
+      if (!routerOnly && cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
         for (const a of cliOptions.addOns) {
           if (a.toLowerCase() === 'start') {
             continue
@@ -157,11 +177,11 @@ export async function normalizeOptions(
       if (cliOptions.toolchain) {
         selectedAddOns.add(cliOptions.toolchain)
       }
-      if (cliOptions.deployment) {
+      if (!routerOnly && cliOptions.deployment) {
         selectedAddOns.add(cliOptions.deployment)
       }
 
-      if (!cliOptions.deployment && opts?.forcedDeployment) {
+      if (!routerOnly && !cliOptions.deployment && opts?.forcedDeployment) {
         selectedAddOns.add(opts.forcedDeployment)
       }
 
@@ -171,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 = {}
@@ -184,7 +208,7 @@ export async function normalizeOptions(
     }
   }
 
-  return {
+  const normalized = {
     projectName: projectName,
     targetDir,
     framework,
@@ -195,7 +219,7 @@ export async function normalizeOptions(
       cliOptions.packageManager ||
       getPackageManager() ||
       DEFAULT_PACKAGE_MANAGER,
-    git: !!cliOptions.git,
+    git: cliOptions.git ?? true,
     install: cliOptions.install,
     chosenAddOns,
     addOnOptions: {
@@ -204,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

@@ -1,5 +1,4 @@
-import fs from 'node:fs'
-import { cancel, confirm, intro, isCancel } from '@clack/prompts'
+import { intro } from '@clack/prompts'
 
 import {
   finalizeAddOns,
@@ -12,8 +11,10 @@ import {
 import {
   getProjectName,
   promptForAddOnOptions,
+  promptForEnvVars,
   selectAddOns,
   selectDeployment,
+  selectExamples,
   selectGit,
   selectPackageManager,
   selectToolchain,
@@ -59,25 +60,11 @@ export async function promptForCreateOptions(
     options.projectName = await getProjectName()
   }
 
-  // Check if target directory is empty
-  if (
-    !cliOptions.force &&
-    fs.existsSync(options.projectName) &&
-    fs.readdirSync(options.projectName).length > 0
-  ) {
-    const shouldContinue = await confirm({
-      message: `Target directory ${options.projectName} is not empty. Do you want to continue?`,
-      initialValue: true,
-    })
-
-    if (isCancel(shouldContinue) || !shouldContinue) {
-      cancel('Operation cancelled.')
-      process.exit(0)
-    }
-  }
-
   // Mode is always file-router (TanStack Start)
   options.mode = 'file-router'
+  const template = cliOptions.template?.toLowerCase().trim()
+  const routerOnly =
+    !!cliOptions.routerOnly || (template ? template !== 'file-router' : false)
 
   // TypeScript is always enabled with file-router
   options.typescript = true
@@ -99,12 +86,20 @@ export async function promptForCreateOptions(
 
   // Deployment selection
   const deployment = showDeploymentOptions
-    ? await selectDeployment(options.framework, cliOptions.deployment)
+    ? routerOnly
+      ? undefined
+      : await selectDeployment(options.framework, cliOptions.deployment)
     : undefined
 
   // 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)
   }
@@ -112,18 +107,20 @@ export async function promptForCreateOptions(
     addOns.add(deployment)
   }
 
-  for (const addOn of forcedAddOns) {
-    addOns.add(addOn)
+  if (!routerOnly) {
+    for (const addOn of forcedAddOns) {
+      addOns.add(addOn)
+    }
   }
 
-  if (Array.isArray(cliOptions.addOns)) {
+  if (!routerOnly && Array.isArray(cliOptions.addOns)) {
     for (const addOn of cliOptions.addOns) {
       if (addOn.toLowerCase() === 'start') {
         continue
       }
       addOns.add(addOn)
     }
-  } else {
+  } else if (!routerOnly) {
     for (const addOn of await selectAddOns(
       options.framework,
       options.mode,
@@ -134,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
@@ -168,7 +170,14 @@ export async function promptForCreateOptions(
     options.addOnOptions = { ...defaultOptions, ...userOptions }
   }
 
-  options.git = cliOptions.git || (await selectGit())
+  // 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

@@ -91,6 +91,23 @@ describe('normalizeOptions', () => {
     expect(solidOptions?.tailwind).toBe(true)
   })
 
+  it('defaults git initialization to enabled', async () => {
+    const options = await normalizeOptions({
+      projectName: 'test',
+    })
+
+    expect(options?.git).toBe(true)
+  })
+
+  it('respects explicit --no-git option', async () => {
+    const options = await normalizeOptions({
+      projectName: 'test',
+      git: false,
+    })
+
+    expect(options?.git).toBe(false)
+  })
+
   it('should handle a starter url', async () => {
     __testRegisterFramework({
       id: 'solid',
@@ -274,6 +291,73 @@ describe('normalizeOptions', () => {
     expect(options?.typescript).toBe(true)
   })
 
+  it('should keep file-router mode in router-only compatibility mode', async () => {
+    const options = await normalizeOptions({
+      projectName: 'test',
+      routerOnly: true,
+    })
+
+    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',
+      name: 'react',
+      getAddOns: () => [
+        {
+          id: 'form',
+          name: 'Form',
+          modes: ['file-router'],
+        },
+        {
+          id: 'nitro',
+          name: 'nitro',
+          modes: ['file-router'],
+          type: 'deployment',
+        },
+        {
+          id: 'biome',
+          name: 'Biome',
+          modes: ['file-router'],
+          type: 'toolchain',
+        },
+      ],
+    })
+
+    const options = await normalizeOptions(
+      {
+        projectName: 'test',
+        framework: 'react-cra',
+        routerOnly: true,
+        addOns: ['form'],
+        deployment: 'nitro',
+        toolchain: 'biome',
+      },
+      ['form'],
+      { forcedDeployment: 'nitro' },
+    )
+
+    expect(options?.chosenAddOns.map((a) => a.id)).toEqual(['biome'])
+  })
+
   it('should handle the funky Windows edge case with CLI parsing', async () => {
     __testRegisterFramework({
       id: 'react-cra',