feat: add blank project preset (#488)

Author: tannerlinsley

.agents/index.md

@@ -14,6 +14,9 @@ npx @tanstack/cli add clerk drizzle
 
 # List available add-ons
 npx @tanstack/cli create --list-add-ons
+
+# Minimal one-route Start app
+npx @tanstack/cli create my-app --blank -y
 ```
 
 ## Monorepo Structure
@@ -70,6 +73,7 @@ node ../cli/packages/cli/dist/index.js create my-app
 | `--toolchain <id>`   | Toolchain (use `--list-add-ons` to see options)         |
 | `--deployment <id>`  | Deployment target (use `--list-add-ons` to see options) |
 | `--template <url-or-id>` | Use template URL/path or built-in ID               |
+| `--blank`              | Minimal project without starter UI or default tooling |
 | `--no-git`           | Skip git init                                           |
 | `--no-install`       | Skip npm install                                        |
 | `-y`                 | Accept defaults                                         |
@@ -81,7 +85,8 @@ node ../cli/packages/cli/dist/index.js create my-app
 | ---------------- | ------- | ---------------------------------------- |
 | `projectName`    | string  | Project name                             |
 | `typescript`     | boolean | Always true (TanStack Start requires TS) |
-| `tailwind`       | boolean | Always true (Tailwind always enabled)    |
+| `tailwind`       | boolean | False for blank unless an add-on requires it |
+| `blank`          | boolean | True when using the blank project preset |
 | `fileRouter`     | boolean | Always true                              |
 | `addOnEnabled`   | object  | `{ [id]: boolean }`                      |
 | `addOnOption`    | object  | `{ [id]: options }`                      |
@@ -138,4 +143,3 @@ skills:
     load: "packages/cli/skills/maintain-custom-addons-dev-watch/SKILL.md"
 <!-- intent-skills:end -->
 
-

.changeset/clean-cats-start.md

@@ -0,0 +1,12 @@
+---
+'@tanstack/cli': minor
+'@tanstack/create': minor
+---
+
+Add a `--blank` project preset that creates a production-ready one-route app
+without starter UI, Tailwind, devtools, test tooling, Intent setup, or unused
+public assets. Pass `--intent` to opt local coding-agent skill mappings back in.
+Also move integration-specific dependencies to their owning add-ons and stop
+shipping an unused test stack in standard Start projects. Explicit styling and
+deployment add-ons remain composable with the blank preset, including when
+added later.

README.md

@@ -39,6 +39,9 @@ npx @tanstack/cli create my-app
 # Create TanStack Start app (recommended)
 npx @tanstack/cli create my-app
 
+# Create a minimal one-route Start app without selection prompts
+npx @tanstack/cli create my-app --blank -y
+
 # Create Router-only SPA (no SSR)
 npx @tanstack/cli create my-app --router-only
 

docs/cli-reference.md

@@ -15,13 +15,14 @@ tanstack create [project-name] [options]
 |--------|-------------|
 | `--add-ons <ids>` | Comma-separated add-on IDs |
 | `--template <url-or-id>` | Template URL/path or built-in template ID |
+| `--blank` | Create a minimal one-route Start project without default starter UI, examples, Tailwind, devtools, or a test stack |
 | `--package-manager <pm>` | `npm`, `pnpm`, `yarn`, `bun`, `deno` |
 | `--framework <name>` | `React`, `Solid` |
 | `--router-only` | Create file-based Router-only app without TanStack Start (add-ons/deployment/template disabled) |
 | `--toolchain <id>` | Toolchain add-on (use `--list-add-ons` to see options) |
 | `--deployment <id>` | Deployment add-on (use `--list-add-ons` to see options) |
 | `--examples` / `--no-examples` | Include or exclude demo/example pages |
-| `--tailwind` / `--no-tailwind` | Deprecated compatibility flags; accepted but ignored (Tailwind is always enabled) |
+| `--tailwind` / `--no-tailwind` | Deprecated compatibility flags for standard projects; blank projects omit Tailwind |
 | `--no-git` | Skip git init |
 | `--no-install` | Skip dependency install |
 | `-y, --yes` | Use defaults, skip prompts |
@@ -36,6 +37,8 @@ tanstack create [project-name] [options]
 ```bash
 # Examples
 tanstack create my-app -y
+tanstack create my-app --blank -y
+tanstack create my-app --blank --deployment cloudflare -y
 tanstack create my-app --add-ons clerk,drizzle,tanstack-query
 tanstack create my-app --router-only --toolchain eslint --no-examples
 tanstack create my-app --template https://example.com/template.json
@@ -44,6 +47,14 @@ tanstack create --list-add-ons --framework React --json
 tanstack create --addon-details drizzle --framework React --json
 ```
 
+`--blank` creates the smallest useful TanStack Start project: one route and no
+default starter interface, examples, Tailwind, devtools, test dependencies, or
+TanStack Intent setup. Pass `--intent` when the project should include local
+skill mappings for coding agents.
+Explicit add-ons and deployment adapters can add their own required files and
+dependencies. Add `-y` to use defaults for every remaining option; when the
+target is non-empty, also pass `--force` or the command exits without writing.
+
 ### Programmatic generation
 
 Use `@tanstack/create/worker` in Cloudflare Workers and other edge SSR runtimes. It does not import the generated template manifest at module startup. Instead, provide a loader for the framework and add-on chunks your Worker supports.
@@ -295,7 +306,7 @@ Removes `^` from version ranges for TanStack packages and adds any missing peer
 
 ## Configuration
 
-Projects include `.tanstack.json`:
+Projects include `.cta.json`:
 
 ```json
 {

docs/quick-start.md

@@ -17,13 +17,25 @@ Interactive prompts guide you through project name, package manager, and add-on
 # Defaults only (TanStack Start + file-router)
 npx @tanstack/cli create my-app -y
 
+# Minimal one-route Start project
+npx @tanstack/cli create my-app --blank -y
+
+# Minimal Start project configured for Cloudflare
+npx @tanstack/cli create my-app --blank --deployment cloudflare -y
+
 # With add-ons
-npx @tanstack/cli create my-app --add-ons tanstack-query,clerk,drizzle
+npx @tanstack/cli create my-app --add-ons tanstack-query,clerk,drizzle -y
 
 # Router-only SPA (no SSR)
-npx @tanstack/cli create my-app --router-only
+npx @tanstack/cli create my-app --router-only -y
 ```
 
+Blank projects omit the default starter interface, examples, Tailwind,
+devtools, test stack, and TanStack Intent setup. Pass `--intent` to include
+local skill mappings for coding agents. Explicit add-ons can add their own
+required files and dependencies. Pass `-y` to skip selection prompts. A
+non-empty target also requires `--force`.
+
 ## Run the Project
 
 ```bash
@@ -34,7 +46,7 @@ pnpm dev
 
 ## Environment Variables
 
-Some add-ons require API keys. After creation:
+Some add-ons require API keys. When the project includes `.env.example`:
 
 ```bash
 cp .env.example .env
@@ -49,9 +61,9 @@ my-app/
 │   ├── routes/          # File-based routing
 │   │   ├── __root.tsx   # Root layout
 │   │   └── index.tsx    # Home page
-│   └── integrations/    # Add-on integration code
-├── .tanstack.json       # CLI config
-└── .env.example         # Required env vars
+│   └── integrations/    # Present when selected add-ons need it
+├── .cta.json            # CLI config
+└── .env.example         # Present when selected add-ons need env vars
 ```
 
 ## Next Steps

examples/react/blog/package.json

@@ -19,7 +19,6 @@
     "@tanstack/react-router-ssr-query": "^1.131.7",
     "@tanstack/react-start": "^1.132.0",
     "@tanstack/router-plugin": "^1.132.0",
-    "lucide-react": "^0.545.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "tailwindcss": "^4.1.18"

packages/cli/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

packages/cli/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

packages/cli/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
 

packages/cli/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
 ```