feat: modernize templates and strengthen e2e release gates

Migrate CRA examples into first-class React templates, expand blocking e2e coverage, and fix store add-on compatibility plus responsive layout issues in generated starters.

Author: tannerlinsley

.agents/index.md

@@ -45,7 +45,7 @@ node ../cli/packages/cli/dist/index.js create my-app
 | Term      | Definition                               | CLI Flag      |
 | --------- | ---------------------------------------- | ------------- |
 | Add-on    | Plugin that extends apps (auth, DB, etc) | `--add-ons`   |
-| Starter   | Reusable preset of add-ons (config only) | `--starter`   |
+| Template  | Reusable project template                  | `--template`  |
 | Framework | React or Solid                           | `--framework` |
 
 ## CLI Commands
@@ -55,7 +55,7 @@ node ../cli/packages/cli/dist/index.js create my-app
 | `tanstack create [name]`        | Create TanStack Start app |
 | `tanstack add [add-ons]`        | Add to existing project   |
 | `tanstack add-on init/compile`  | Create custom add-on      |
-| `tanstack starter init/compile` | Create custom starter     |
+| `tanstack template init/compile` | Create custom template    |
 | `tanstack mcp [--sse]`          | Start MCP server          |
 | `tanstack pin-versions`         | Pin TanStack packages     |
 
@@ -67,7 +67,7 @@ node ../cli/packages/cli/dist/index.js create my-app
 | `--framework <name>` | React or Solid                                          |
 | `--toolchain <id>`   | Toolchain (use `--list-add-ons` to see options)         |
 | `--deployment <id>`  | Deployment target (use `--list-add-ons` to see options) |
-| `--starter <url>`    | Use starter preset                                      |
+| `--template <url-or-id>` | Use template URL/path or built-in ID               |
 | `--no-git`           | Skip git init                                           |
 | `--no-install`       | Skip npm install                                        |
 | `-y`                 | Accept defaults                                         |
@@ -119,3 +119,10 @@ node packages/cli/dist/index.js create test --add-ons http://localhost:9080/info
 | `packages/create/src/frameworks/` | Framework implementations |
 | `packages/create/src/app-*.ts`    | App creation logic        |
 | `.tanstack.json`                  | Generated project config  |
+
+
+## Playbook Skills
+
+This project uses TanStack Playbooks. Run `npx playbook list` to discover
+available AI coding skills. Before working with a library that has skills,
+read the relevant SKILL.md file at the path shown in the list output.

.github/workflows/e2e-opportunistic-matrix.yml

@@ -0,0 +1,56 @@
+name: E2E Opportunistic Matrix
+
+on:
+  schedule:
+    - cron: '0 8 * * *'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
+
+permissions:
+  contents: read
+
+jobs:
+  matrix-e2e:
+    name: Matrix (${{ matrix.scenario }})
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    strategy:
+      fail-fast: false
+      matrix:
+        scenario:
+          - react-base-pnpm
+          - react-base-npm
+          - solid-base-npm
+          - react-template-resume
+          - react-template-ecommerce
+          - react-addons-core-pnpm
+          - solid-addons-core-pnpm
+          - react-toolchain-deploy
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.1
+        with:
+          fetch-depth: 0
+      - name: Setup Tools
+        uses: tanstack/config/.github/setup@main
+      - name: Build
+        run: pnpm build
+      - name: Install Playwright Chrome
+        run: pnpm --filter @tanstack/cli exec playwright install --with-deps chrome
+      - name: Run Matrix Scenario
+        env:
+          E2E_MATRIX_SCENARIO: ${{ matrix.scenario }}
+        run: pnpm --filter @tanstack/cli test:e2e:matrix
+      - name: Upload Playwright Report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report-${{ matrix.scenario }}
+          path: packages/cli/playwright-report
+          if-no-files-found: ignore

.github/workflows/pr.yml

@@ -14,8 +14,8 @@ permissions:
   contents: read
 
 jobs:
-  test:
-    name: Test
+  test-unit:
+    name: Test (Unit)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -26,8 +26,8 @@ jobs:
         uses: tanstack/config/.github/setup@main
       - name: Build
         run: pnpm build
-      - name: Test
-        run: pnpm test
+      - name: Test Unit
+        run: pnpm test:unit
   provenance:
     name: Provenance
     runs-on: ubuntu-latest
@@ -40,3 +40,19 @@ jobs:
         uses: danielroe/provenance-action@v0.1.1
         with:
           fail-on-downgrade: true
+  test-e2e:
+    name: Test (E2E Blocking)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.1
+        with:
+          fetch-depth: 0
+      - name: Setup Tools
+        uses: tanstack/config/.github/setup@main
+      - name: Build
+        run: pnpm build
+      - name: Install Playwright Chrome
+        run: pnpm --filter @tanstack/cli exec playwright install --with-deps chrome
+      - name: Test E2E Blocking
+        run: pnpm test:e2e

.github/workflows/release.yml

@@ -30,8 +30,12 @@ jobs:
         uses: tanstack/config/.github/setup@main
       - name: Build
         run: pnpm build
-      - name: Test
-        run: pnpm test
+      - name: Test Unit
+        run: pnpm test:unit
+      - name: Install Playwright Chrome
+        run: pnpm --filter @tanstack/cli exec playwright install --with-deps chrome
+      - name: E2E Blocking
+        run: pnpm --filter @tanstack/cli test:e2e
       - name: Run Changesets (version or publish)
         uses: changesets/action@v1.5.3
         with:

.gitignore

@@ -16,4 +16,6 @@ my-app
 
 .content-collections
 
-coverage
+coverage
+playwright-report
+test-results

CONTRIBUTING.md

@@ -40,26 +40,27 @@ npx serve .add-on -l 9080
 node ../cli/packages/cli/dist/index.js create my-app --add-ons http://localhost:9080/info.json
 ```
 
-### Testing Starters Locally
+### Testing Templates Locally
 
 ```bash
-# In your starter directory
-npx serve .starter -l 9080
+# In your template directory
+npx serve .template -l 9080
 
-# Create app with local starter
-node ../cli/packages/cli/dist/index.js create my-app --starter http://localhost:9080/starter.json
+# Create app with local template
+node ../cli/packages/cli/dist/index.js create my-app --template http://localhost:9080/template.json
 ```
 
-## Dev Watch Mode
+## Dev Mode
 
-Watch framework files and auto-rebuild:
+Create a sandbox app, watch built-in framework templates/add-ons, and run the sandbox dev server:
 
 ```bash
-rm -rf test-app && node packages/cli/dist/index.js create \
-  --dev-watch ./packages/create/src/frameworks/react \
-  test-app --add-ons shadcn
+rm -rf test-app && node packages/cli/dist/index.js dev \
+  test-app --framework React --add-ons shadcn
 ```
 
+The legacy `create --dev-watch <path>` flow still works for direct watch path control.
+
 ## Developing Create UI
 
 The UI requires running three things:

docs/cli-reference.md

@@ -14,10 +14,10 @@ tanstack create [project-name] [options]
 | Option | Description |
 |--------|-------------|
 | `--add-ons <ids>` | Comma-separated add-on IDs |
-| `--starter <url>` | Starter URL or local path |
+| `--template <url-or-id>` | Template URL/path or built-in template ID |
 | `--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/starter disabled) |
+| `--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 |
@@ -38,7 +38,8 @@ tanstack create [project-name] [options]
 tanstack create my-app -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 --starter https://example.com/starter.json
+tanstack create my-app --template https://example.com/template.json
+tanstack create my-app --template ecommerce
 ```
 
 ---
@@ -91,27 +92,25 @@ See [Creating Add-ons](./creating-add-ons.md) for full guide.
 
 ---
 
-## tanstack starter
+## tanstack template
 
-Create reusable project presets.
+Create reusable project templates.
 
 ### init
 
 ```bash
-tanstack starter init
+tanstack template init
 ```
 
-Creates `starter-info.json` and `starter.json`.
+Creates `template-info.json` and `template.json`.
 
 ### compile
 
 ```bash
-tanstack starter compile
+tanstack template compile
 ```
 
-See [Starters](./starters.md) for full guide.
-
----
+See [Templates](./templates.md) for full guide.
 
 ## tanstack mcp
 
@@ -158,4 +157,4 @@ Projects include `.tanstack.json`:
 }
 ```
 
-Used by `add-on init` and `starter init` to detect changes.
+Used by `add-on init` and `template init` to detect changes.

docs/overview.md

@@ -12,7 +12,7 @@ npx @tanstack/cli create my-app
 ## Features
 
 - **Add-ons** - Auth, database, deployment, monitoring ([full list](./add-ons.md))
-- **Starters** - Reusable project presets ([docs](./starters.md))
+- **Templates** - Reusable project templates ([docs](./templates.md))
 - **MCP Server** - AI agent support ([docs](./mcp/overview.md))
 
 ## Next Steps

docs/starters.md

@@ -1,109 +1,6 @@
 ---
 id: starters
-title: Starters
+title: Starters (Legacy)
 ---
 
-Starters are reusable presets of project setup choices. They capture configuration, not source files.
-
-## Use a Starter
-
-```bash
-tanstack create my-app --starter https://example.com/starter.json
-tanstack create my-app --starter ./local-starter.json
-```
-
-You can also set a starter in the UI flow:
-
-```bash
-tanstack create my-app --ui
-```
-
-Then use **Set Starter** and paste the URL to your hosted `starter.json`.
-
-## Create a Starter
-
-```bash
-# 1. Create project with desired setup
-tanstack create my-preset --add-ons clerk,drizzle,sentry
-
-# 2. Initialize starter
-cd my-preset
-tanstack starter init
-
-# 3. Edit starter-info.json (name/description/banner), then compile
-tanstack starter compile
-
-# 4. Use or distribute starter.json
-tanstack create new-app --starter ./starter.json
-```
-
-## Maintain a Starter
-
-When you update your source preset project:
-
-```bash
-cd my-preset
-tanstack starter compile
-```
-
-Commit and publish the updated `starter.json` to the same URL (or a versioned URL) used by your team.
-
-Recommended workflow:
-
-1. Keep your source preset project in git.
-2. Run `tanstack starter compile` whenever add-ons/options change.
-3. Publish `starter.json` where it can be fetched over HTTPS.
-4. Use that URL with `--starter` (CLI) or **Set Starter** (UI).
-
-## Starter Schema
-
-`starter-info.json`:
-
-```json
-{
-  "id": "my-saas",
-  "name": "SaaS Starter",
-  "description": "Auth, database, monitoring",
-  "framework": "react",
-  "mode": "file-router",
-  "typescript": true,
-  "tailwind": true,
-  "addOns": ["clerk", "drizzle", "sentry"],
-  "addOnOptions": {
-    "drizzle": { "database": "postgres" }
-  }
-}
-```
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `id` | Yes | Unique identifier |
-| `name` | Yes | Display name |
-| `description` | Yes | Brief description |
-| `framework` | Yes | `react` or `solid` |
-| `mode` | Yes | `file-router` |
-| `typescript` | Yes | Enable TypeScript |
-| `tailwind` | Yes | Include Tailwind |
-| `addOns` | Yes | Add-on IDs |
-| `addOnOptions` | No | Per-add-on config |
-| `banner` | No | Image URL shown in UI |
-
-### Banner Image
-
-`banner` should be a publicly accessible image URL (PNG/JPG/WebP) used by the create UI. A screenshot of the starter works well.
-
-Example:
-
-```json
-{
-  "banner": "https://example.com/my-starter-banner.png"
-}
-```
-
-## Starter vs Add-on
-
-| | Starter | Add-on |
-|-|---------|--------|
-| Contains code | No | Yes |
-| Adds files | No | Yes |
-| Configuration preset | Yes | No |
+This page has moved to [Templates](./templates.md).