@tanstack/cli 0.69.6 → 0.70.0

package/dist/cli.js

@@ -111,6 +111,7 @@ function getCreateTelemetryProperties(projectName, options) {
         command_variant: getCreateCommandVariant(options),
         deployment: options.deployment ? sanitizeId(options.deployment) : undefined,
         examples: options.examples,
+        blank: !!options.blank,
         framework: options.framework ? sanitizeId(options.framework) : undefined,
         git: options.git,
         install: options.install !== false,
@@ -137,6 +138,7 @@ function getResolvedCreateTelemetryProperties(finalOptions, cliOptions) {
         add_on_ids: addOnIds,
         deployment: deployment ? sanitizeId(deployment.id) : undefined,
         examples: includeExamples,
+        blank: finalOptions.projectPreset === 'blank',
         framework: sanitizeId(finalOptions.framework.id),
         git: finalOptions.git,
         install: finalOptions.install !== false,
@@ -153,7 +155,7 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
     let currentTelemetry;
     const environment = createUIEnvironment(appName, false, () => currentTelemetry);
     const program = new Command();
-    async function confirmTargetDirectorySafety(targetDir, forced) {
+    async function confirmTargetDirectorySafety(targetDir, forced, nonInteractive) {
         if (forced) {
             return;
         }
@@ -166,6 +168,9 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
         if (fs.readdirSync(targetDir).length === 0) {
             return;
         }
+        if (nonInteractive) {
+            throw new Error(`Target directory "${targetDir}" already exists and is not empty. Pass --force to continue non-interactively.`);
+        }
         const shouldContinue = await confirm({
             message: `Target directory "${targetDir}" already exists and is not empty. Continue anyway?`,
             initialValue: false,
@@ -181,6 +186,9 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
         lines.push(`  Location:        ${finalOptions.targetDir}`);
         lines.push(`  Framework:       ${finalOptions.framework.name}`);
         lines.push(`  Mode:            ${finalOptions.mode}`);
+        if (finalOptions.projectPreset === 'blank') {
+            lines.push(`  Preset:          blank`);
+        }
         lines.push(`  Package manager: ${finalOptions.packageManager}`);
         if (finalOptions.starter) {
             lines.push(`  Template:        ${finalOptions.starter.name}`);
@@ -361,7 +369,7 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
             console.log(chalk.gray('├─') + ' ' + chalk.yellow('⟳') + ' installing packages...');
         }
         const silentEnvironment = createUIEnvironment(appName, true, () => currentTelemetry);
-        await confirmTargetDirectorySafety(normalizedOpts.targetDir, options.force);
+        await confirmTargetDirectorySafety(normalizedOpts.targetDir, options.force, !!options.nonInteractive || !!options.yes);
         await createApp(silentEnvironment, normalizedOpts);
         console.log(chalk.gray('└─') + ' ' + chalk.green('✓') + ` app created`);
         // Now start the dev watch mode
@@ -449,6 +457,15 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
         .description(`${appName} CLI`)
         .version(VERSION, '-v, --version', 'output the current version');
     addHiddenAgentFlag(program);
+    function validateCreateCommandOptions(options) {
+        const legacyCreateFlags = validateLegacyCreateFlags(options);
+        if (legacyCreateFlags.error) {
+            throw new Error(legacyCreateFlags.error);
+        }
+        for (const warning of legacyCreateFlags.warnings) {
+            log.warn(warning);
+        }
+    }
     // Helper to create the create command action handler
     async function handleCreate(projectName, options) {
         try {
@@ -456,13 +473,7 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
                 json: options.json,
                 properties: getCreateTelemetryProperties(projectName, options),
             }, async (telemetry) => {
-                const legacyCreateFlags = validateLegacyCreateFlags(options);
-                if (legacyCreateFlags.error) {
-                    throw new Error(legacyCreateFlags.error);
-                }
-                for (const warning of legacyCreateFlags.warnings) {
-                    log.warn(warning);
-                }
+                validateCreateCommandOptions(options);
                 if (options.listAddOns) {
                     const addOns = await getAllAddOns(getFrameworkByName(options.framework || defaultFramework || 'React'), defaultMode);
                     const visibleAddOns = addOns.filter((a) => !forcedAddOns.includes(a.id));
@@ -666,7 +677,7 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
                 if (cameFromPrompts) {
                     await confirmCreateOptions(finalOptions);
                 }
-                await confirmTargetDirectorySafety(finalOptions.targetDir, options.force);
+                await confirmTargetDirectorySafety(finalOptions.targetDir, options.force, nonInteractive);
                 await createApp(environment, finalOptions);
             });
         }
@@ -704,8 +715,9 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
             .option('--dev-watch <path>', 'Watch a framework directory for changes and auto-rebuild')
             .option('--run-dev', 'Run the app dev server alongside dev-watch', false)
             .option('--router-only', 'Use router-only compatibility mode (file-based routing without TanStack Start)')
-            .option('--tailwind', 'Deprecated: compatibility flag; Tailwind is always enabled')
-            .option('--no-tailwind', 'Deprecated: compatibility flag; Tailwind opt-out is ignored')
+            .option('--blank', 'Create a minimal one-route app without default starter UI, Tailwind, devtools, or tests')
+            .option('--tailwind', 'Deprecated: compatibility flag; standard scaffolds always enable Tailwind')
+            .option('--no-tailwind', 'Deprecated: compatibility flag; use --blank for a project without Tailwind')
             .option('--examples', 'include demo/example pages')
             .option('--no-examples', 'exclude demo/example pages');
         if (deployments.size > 0) {
@@ -772,6 +784,7 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
                     run_dev: true,
                 },
             }, async () => {
+                validateCreateCommandOptions(options);
                 const frameworkName = options.framework || defaultFramework || 'React';
                 const framework = getFrameworkByName(frameworkName);
                 if (!framework) {

package/dist/command-line.js

@@ -217,6 +217,25 @@ export async function listTemplateChoices(preferredFramework) {
 export function validateLegacyCreateFlags(cliOptions) {
     const warnings = [];
     const legacyTemplate = getLegacyTemplateValue(cliOptions.template);
+    if (cliOptions.blank &&
+        (cliOptions.starter || cliOptions.template || cliOptions.templateId)) {
+        return {
+            warnings,
+            error: '--blank cannot be combined with --starter, --template, or --template-id.',
+        };
+    }
+    if (cliOptions.blank && cliOptions.examples === true) {
+        return {
+            warnings,
+            error: '--blank cannot be combined with --examples.',
+        };
+    }
+    if (cliOptions.blank && cliOptions.tailwind === true) {
+        return {
+            warnings,
+            error: '--blank cannot be combined with --tailwind.',
+        };
+    }
     if (cliOptions.starter) {
         warnings.push('The --starter flag is deprecated; prefer --template instead. Backward compatibility remains for now.');
     }
@@ -239,10 +258,10 @@ export function validateLegacyCreateFlags(cliOptions) {
         warnings.push('Ignoring --template-id 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.');
+        warnings.push('The --tailwind flag is deprecated and ignored. Tailwind is enabled in standard TanStack Start scaffolds.');
     }
-    if (cliOptions.tailwind === false) {
-        warnings.push('The --no-tailwind flag is deprecated and ignored. Tailwind opt-out is intentionally unsupported to keep add-on permutations maintainable; remove Tailwind after scaffolding if needed.');
+    if (cliOptions.tailwind === false && !cliOptions.blank) {
+        warnings.push('The --no-tailwind flag is deprecated and ignored for standard scaffolds. Use --blank to create a minimal project without Tailwind.');
     }
     if (!legacyTemplate) {
         return { warnings };
@@ -283,6 +302,7 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
     // Mode is always file-router (TanStack Start)
     let mode = 'file-router';
     let routerOnly = !!cliOptions.routerOnly;
+    const blank = cliOptions.blank === true;
     const legacyTemplate = getLegacyTemplateValue(cliOptions.template);
     if (!cliOptions.starter) {
         if (cliOptions.template && !legacyTemplate) {
@@ -300,12 +320,11 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
         cliOptions.starter = cliOptions.templateId;
     }
     const preferredFramework = (cliOptions.framework || 'react').toLowerCase();
-    const starter = !routerOnly && cliOptions.starter
+    const starter = !routerOnly && !blank && cliOptions.starter
         ? await loadStarter(await resolveStarterSpecifier(cliOptions.starter, preferredFramework))
         : undefined;
-    // TypeScript and Tailwind are always enabled with TanStack Start
+    // TypeScript is always enabled with TanStack Start.
     const typescript = true;
-    const tailwind = true;
     if (starter) {
         cliOptions.framework = starter.framework;
         mode = starter.mode;
@@ -349,11 +368,12 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
         }
         return [];
     }
-    const includeExamples = cliOptions.examples ?? !routerOnly;
+    const includeExamples = blank ? false : (cliOptions.examples ?? !routerOnly);
     const chosenAddOnsRaw = await selectAddOns();
     const chosenAddOns = includeExamples
         ? chosenAddOnsRaw
         : chosenAddOnsRaw.filter((addOn) => addOn.type !== 'example');
+    const tailwind = !blank || chosenAddOns.some((addOn) => addOn.tailwind === true);
     // Handle add-on configuration option
     let addOnOptionsFromCLI = {};
     if (cliOptions.addOnConfig) {
@@ -377,13 +397,14 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
             DEFAULT_PACKAGE_MANAGER,
         git: cliOptions.git ?? true,
         install: cliOptions.install,
-        intent: cliOptions.intent ?? true,
+        intent: cliOptions.intent ?? !blank,
         chosenAddOns,
         addOnOptions: {
             ...populateAddOnOptionsDefaults(chosenAddOns),
             ...addOnOptionsFromCLI,
         },
         starter: starter,
+        projectPreset: blank ? 'blank' : 'default',
     };
     normalized.includeExamples =
         includeExamples;

package/dist/options.js

@@ -5,6 +5,7 @@ import { listTemplateChoices, resolveStarterSpecifier, } from './command-line.js
 import { resolveProjectLocation, validateProjectName, } from './utils.js';
 export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], forcedDeployment, showDeploymentOptions = true, defaultFrameworkId, }) {
     const options = {};
+    const blank = cliOptions.blank === true;
     if (cliOptions.framework) {
         options.framework = getFrameworkById(cliOptions.framework);
     }
@@ -47,7 +48,7 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], fo
             cliOptions.starter = cliOptions.templateId;
         }
     }
-    if (!routerOnly && !cliOptions.starter) {
+    if (!routerOnly && !blank && !cliOptions.starter) {
         const starterChoices = await listTemplateChoices(options.framework.id);
         const selectedTemplateId = await selectTemplate(starterChoices.map((choice) => ({
             id: choice.id,
@@ -58,7 +59,7 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], fo
             cliOptions.starter = selectedTemplateId;
         }
     }
-    const starter = !routerOnly && cliOptions.starter
+    const starter = !routerOnly && !blank && cliOptions.starter
         ? await loadStarter(await resolveStarterSpecifier(cliOptions.starter, options.framework.id))
         : undefined;
     if (starter) {
@@ -77,7 +78,9 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], fo
             detectedPackageManager || (await selectPackageManager());
     }
     // Toolchain selection
-    const toolchain = await selectToolchain(options.framework, cliOptions.toolchain);
+    const toolchain = blank && cliOptions.toolchain === undefined
+        ? undefined
+        : await selectToolchain(options.framework, cliOptions.toolchain);
     // Deployment selection
     let deployment;
     if (routerOnly) {
@@ -86,6 +89,9 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], fo
     else if (cliOptions.deployment) {
         deployment = cliOptions.deployment;
     }
+    else if (blank) {
+        deployment = forcedDeployment;
+    }
     else if (showDeploymentOptions) {
         deployment = await selectDeployment(options.framework, cliOptions.deployment, forcedDeployment);
     }
@@ -95,7 +101,9 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], fo
     // Add-ons selection
     const addOns = new Set();
     // Examples/demo pages are enabled by default
-    const includeExamples = cliOptions.examples ?? (routerOnly ? false : await selectExamples());
+    const includeExamples = blank
+        ? false
+        : (cliOptions.examples ?? (routerOnly ? false : await selectExamples()));
     options.includeExamples =
         includeExamples;
     if (toolchain) {
@@ -120,7 +128,7 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], fo
             addOns.add(addOn);
         }
     }
-    else if (!routerOnly) {
+    else if (!routerOnly && !blank) {
         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);
         }
@@ -134,8 +142,9 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], fo
     options.chosenAddOns = includeExamples
         ? chosenAddOns
         : chosenAddOns.filter((addOn) => addOn.type !== 'example');
-    // Tailwind is always enabled
-    options.tailwind = true;
+    options.tailwind =
+        !blank || options.chosenAddOns.some((addOn) => addOn.tailwind === true);
+    options.projectPreset = blank ? 'blank' : 'default';
     // Prompt for add-on options in interactive mode
     if (Array.isArray(cliOptions.addOns)) {
         // Non-interactive mode: use defaults
@@ -156,6 +165,7 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], fo
         envVarValues;
     options.git = cliOptions.git ?? (await selectGit());
     options.install = cliOptions.install ?? (await selectInstall());
+    options.intent = cliOptions.intent ?? !blank;
     if (starter) {
         options.starter = starter;
     }

package/dist/types/types.d.ts

@@ -23,6 +23,7 @@ export interface CliOptions {
     addOnConfig?: string;
     force?: boolean;
     routerOnly?: boolean;
+    blank?: boolean;
     template?: string;
     tailwind?: boolean;
     examples?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/cli",
-  "version": "0.69.6",
+  "version": "0.70.0",
   "description": "TanStack CLI",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,7 +44,7 @@
     "tempy": "^3.1.0",
     "validate-npm-package-name": "^7.0.0",
     "zod": "^3.24.2",
-    "@tanstack/create": "0.68.5"
+    "@tanstack/create": "0.69.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",

package/skills/add-addons-existing-app/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Apply integrations to existing projects with tanstack add, including
   add-on id resolution, dependency chains, option prompts, and .cta.json
   project metadata preconditions.
-type: core
-library: tanstack-cli
-library_version: "0.62.1"
+metadata:
+  type: core
+  library: tanstack-cli
+  library_version: "0.62.1"
 ---
 
 # Add Add-ons To Existing App

package/skills/choose-ecosystem-integrations/SKILL.md

@@ -5,9 +5,10 @@ description: >
   tanstack ecosystem --json, tanstack create --list-add-ons --json, and
   tanstack create --addon-details --json. Covers exclusive categories,
   provider options, and router-only compatibility constraints.
-type: composition
-library: tanstack-cli
-library_version: "0.62.1"
+metadata:
+  type: composition
+  library: tanstack-cli
+  library_version: "0.62.1"
 requires:
   - create-app-scaffold
   - query-docs-library-metadata

package/skills/create-app-scaffold/SKILL.md

@@ -2,12 +2,13 @@
 name: create-app-scaffold
 description: >
   Scaffold a TanStack app with tanstack create using --framework, --template,
-  --toolchain, --deployment, --add-ons, and --router-only. Covers flag
+  --toolchain, --deployment, --add-ons, --blank, and --router-only. Covers flag
   compatibility, non-interactive defaults, and intent-preserving command
   construction.
-type: core
-library: tanstack-cli
-library_version: "0.62.1"
+metadata:
+  type: core
+  library: tanstack-cli
+  library_version: "0.70.0"
 ---
 
 # Create App Scaffold
@@ -37,6 +38,20 @@ npx @tanstack/cli create acme-solid \
   -y
 ```
 
+### Start from a minimal production-ready scaffold
+
+Use `--blank` when the task does not need the default starter UI, examples,
+Tailwind, devtools, test tooling, or local Intent setup. Explicit integrations
+remain composable; add `--intent` when the generated project should contain
+skill mappings for later coding-agent work.
+
+```bash
+npx @tanstack/cli create acme-web \
+  --blank \
+  --deployment cloudflare \
+  -y
+```
+
 ### Use router-only mode for compatibility scaffolds only
 
 ```bash
@@ -75,7 +90,7 @@ In non-interactive runs, empty add-on selection can complete with defaults and s
 
 Source: https://github.com/TanStack/cli/issues/234
 
-### HIGH Assume --no-tailwind is still supported
+### HIGH Avoid --no-tailwind; use --blank for a minimal scaffold
 
 Wrong:
 ```bash
@@ -84,12 +99,31 @@ npx @tanstack/cli create my-app --no-tailwind -y
 
 Correct:
 ```bash
-npx @tanstack/cli create my-app -y
+npx @tanstack/cli create my-app --blank -y
+```
+
+`--no-tailwind` remains a deprecated compatibility flag for standard
+scaffolds. `--blank` is the supported preset for a minimal project without
+Tailwind.
+
+Source: packages/cli/src/command-line.ts:386
+
+### HIGH Combine --blank with a template, examples, or --tailwind
+
+Wrong:
+```bash
+npx @tanstack/cli create my-app --blank --template ecommerce -y
 ```
 
-`--no-tailwind` is deprecated and ignored, so output still includes Tailwind and diverges from expected stack constraints.
+Correct:
+```bash
+npx @tanstack/cli create my-app --blank --add-ons drizzle -y
+```
 
-Source: packages/cli/src/command-line.ts:369
+Templates, examples, and `--tailwind` replace the output constraints that
+`--blank` guarantees, so the CLI rejects those combinations. Deployment,
+toolchain, and add-on selections remain supported; a selected styling add-on
+can opt the generated app back into Tailwind when it requires it.
 
 ### CRITICAL Combine router-only with template/deployment/add-ons
 

package/skills/create-app-scaffold/references/create-flag-compatibility-matrix.md

@@ -1,6 +1,6 @@
 # Create Flag Compatibility Matrix
 
-Targets `@tanstack/cli` v0.62.1.
+Targets `@tanstack/cli` v0.70.0.
 
 ## Compatibility
 
@@ -12,7 +12,8 @@ Targets `@tanstack/cli` v0.62.1.
 | `--deployment` | yes | no | Ignored in router-only mode. |
 | `--template` / `--starter` | yes | no | Ignored in router-only mode. |
 | `--template-id` | yes | no | Ignored in router-only mode. |
-| `--tailwind` / `--no-tailwind` | deprecated/ignored | deprecated/ignored | Tailwind is always enabled. |
+| `--blank` | yes | yes | Omits starter UI, examples, Tailwind, devtools, and test tooling unless an explicit integration requires them. Cannot be combined with a template, `--examples`, or `--tailwind`. |
+| `--tailwind` / `--no-tailwind` | deprecated/ignored | deprecated/ignored | Standard scaffolds enable Tailwind; use `--blank` for the supported minimal preset. |
 
 Source: `packages/cli/src/command-line.ts:337`
 
@@ -29,6 +30,9 @@ Source: `packages/cli/src/command-line.ts:337`
 # Full scaffold preset
 npx @tanstack/cli create app --framework react --add-ons tanstack-query --deployment netlify -y
 
+# Minimal Start preset
+npx @tanstack/cli create app --blank --framework react --deployment cloudflare -y
+
 # Router-only preset
 npx @tanstack/cli create app --router-only --framework react --toolchain biome -y
 ```

package/skills/create-app-scaffold/references/framework-adapters.md

@@ -1,6 +1,6 @@
 # Framework Adapter Options
 
-Targets `@tanstack/cli` v0.61.0.
+Targets `@tanstack/cli` v0.70.0.
 
 ## Supported values
 

package/skills/maintain-custom-addons-dev-watch/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Build and iterate custom add-ons/templates with tanstack add-on init,
   add-on compile, add-on dev, and tanstack create --dev-watch, including sync
   loop preconditions, watch-path validation, and project metadata constraints.
-type: lifecycle
-library: tanstack-cli
-library_version: "0.62.1"
+metadata:
+  type: lifecycle
+  library: tanstack-cli
+  library_version: "0.62.1"
 requires:
   - add-addons-existing-app
 ---

package/skills/query-docs-library-metadata/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Retrieve machine-readable context with tanstack libraries, tanstack doc,
   tanstack search-docs, tanstack create --list-add-ons --json, and
   --addon-details for agent-safe discovery and preflight validation.
-type: core
-library: tanstack-cli
-library_version: "0.62.1"
+metadata:
+  type: core
+  library: tanstack-cli
+  library_version: "0.62.1"
 ---
 
 # Query Docs And Library Metadata