@tanstack/cli 0.61.1 → 0.62.0

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@tanstack/cli",
-  "version": "0.61.1",
+  "version": "0.62.0",
   "description": "TanStack CLI",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist",
+    "skills"
+  ],
   "bin": {
     "tanstack": "./dist/bin.js"
   },

package/skills/CHANGELOG.md

@@ -0,0 +1,18 @@
+## 2026-03-02
+
+### Updated for @tanstack/cli v0.61.0
+
+**Breaking changes:**
+- create-app-scaffold: documents router-only compatibility behavior where template/deployment/add-on intent is ignored.
+- add-addons-existing-app: enforces `.cta.json` metadata precondition for add flows.
+
+**Deprecation updates:**
+- create-app-scaffold: `--no-tailwind` treated as deprecated/ignored; recommends post-scaffold removal flow.
+- query-docs-library-metadata: deprecated alias discovery patterns replaced with `tanstack` command namespace.
+
+**New skills:**
+- create-app-scaffold: deterministic app generation and flag compatibility.
+- add-addons-existing-app: add-on layering into existing repos.
+- query-docs-library-metadata: JSON discovery/doc retrieval for agents.
+- choose-ecosystem-integrations: partner-to-add-on mapping and exclusivity handling.
+- maintain-custom-addons-dev-watch: custom add-on authoring and dev-watch lifecycle.

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

@@ -0,0 +1,113 @@
+---
+name: add-addons-existing-app
+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.61.0"
+---
+
+# Add Add-ons To Existing App
+
+Use this skill when the project already exists and you need to layer add-ons safely without breaking dependency or metadata assumptions.
+
+## Setup
+
+```bash
+npx @tanstack/cli add clerk drizzle
+```
+
+## Core Patterns
+
+### Add multiple integrations in one pass
+
+```bash
+npx @tanstack/cli add tanstack-query drizzle
+```
+
+### Resolve candidate ids before applying
+
+```bash
+npx @tanstack/cli create --list-add-ons --json
+```
+
+### Validate optionized add-ons before install
+
+```bash
+npx @tanstack/cli create --addon-details prisma --json
+```
+
+## Common Mistakes
+
+### CRITICAL Run tanstack add without .cta.json
+
+Wrong:
+```bash
+npx @tanstack/cli add clerk
+```
+
+Correct:
+```bash
+# Run in a project scaffolded by TanStack CLI (contains .cta.json), then:
+npx @tanstack/cli add clerk
+```
+
+Add flows depend on persisted scaffold metadata, so commands can fail or apply incomplete config when `.cta.json` is missing.
+
+Source: packages/create/src/custom-add-ons/shared.ts:158
+
+### HIGH Use invalid add-on id
+
+Wrong:
+```bash
+npx @tanstack/cli add drizle
+```
+
+Correct:
+```bash
+npx @tanstack/cli add drizzle
+```
+
+Unknown ids stop resolution and force manual correction before any add-on work proceeds.
+
+Source: packages/create/src/add-ons.ts:44
+
+### HIGH Ignore add-on dependency requirements
+
+Wrong:
+```bash
+npx @tanstack/cli add custom-addon-with-missing-deps
+```
+
+Correct:
+```bash
+npx @tanstack/cli add required-dependency custom-addon-with-missing-deps
+```
+
+Add-ons with `dependsOn` can fail during finalization if required dependencies are not present.
+
+Source: packages/create/src/add-ons.ts:48
+
+### MEDIUM Assume old Windows path bug still present
+
+Wrong:
+```bash
+# Avoid tanstack add on Windows and patch manually
+```
+
+Correct:
+```bash
+npx @tanstack/cli add clerk
+```
+
+Avoiding supported workflows based on historical bug reports causes unnecessary manual drift. Fixed in newer versions, but agents trained on older threads may still avoid this path.
+
+Source: https://github.com/TanStack/cli/issues/329
+
+### HIGH Tension: Backwards support vs deterministic automation
+
+This domain's patterns conflict with maintain-custom-addons-dev-watch. Automation that assumes universal add flows tends to fail because legacy compatibility still relies on hidden scaffold metadata.
+
+See also: maintain-custom-addons-dev-watch/SKILL.md § Common Mistakes

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

@@ -0,0 +1,140 @@
+---
+name: choose-ecosystem-integrations
+description: >
+  Map tanstack ecosystem partner metadata to installable add-on ids using
+  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.61.0"
+requires:
+  - create-app-scaffold
+  - query-docs-library-metadata
+---
+
+This skill requires familiarity with scaffold and discovery workflows. Read `create-app-scaffold` and `query-docs-library-metadata` first.
+
+# Choose Ecosystem Integrations
+
+Use this skill at the seam between user requirements and valid CLI integration choices.
+
+## Setup
+
+```bash
+npx @tanstack/cli ecosystem --json
+npx @tanstack/cli create --list-add-ons --json
+```
+
+## Core Patterns
+
+### Map partner intent to add-on ids explicitly
+
+```bash
+npx @tanstack/cli ecosystem --category database --json
+npx @tanstack/cli create --list-add-ons --json
+```
+
+### Inspect option surfaces before final provider choice
+
+```bash
+npx @tanstack/cli create --addon-details drizzle --json
+npx @tanstack/cli create --addon-details prisma --json
+```
+
+### Enforce one choice per exclusive category
+
+```bash
+npx @tanstack/cli create my-app \
+  --framework react \
+  --add-ons clerk,drizzle \
+  --deployment cloudflare \
+  -y
+```
+
+## Common Mistakes
+
+### HIGH Treat ecosystem partner id as add-on id
+
+Wrong:
+```bash
+npx @tanstack/cli add <partner-id-from-ecosystem>
+```
+
+Correct:
+```bash
+npx @tanstack/cli ecosystem --json
+npx @tanstack/cli create --list-add-ons --json
+npx @tanstack/cli add <mapped-addon-id>
+```
+
+`ecosystem` includes partners that are not directly installable add-ons, so direct reuse of partner ids can fail late in add/apply flows.
+
+Source: tanstack ecosystem --json output + tanstack create --list-add-ons --json output
+
+### HIGH Skip addon-details before choosing provider
+
+Wrong:
+```bash
+npx @tanstack/cli create my-app --add-ons prisma -y
+```
+
+Correct:
+```bash
+npx @tanstack/cli create --addon-details prisma --json
+npx @tanstack/cli create my-app --add-ons prisma -y
+```
+
+Optionized providers can default silently, producing the wrong data-layer stack for the requested integration.
+
+Source: tanstack create --addon-details prisma --json
+
+### HIGH Select multiple exclusive integrations together
+
+Wrong:
+```bash
+npx @tanstack/cli create my-app --add-ons clerk,workos -y
+```
+
+Correct:
+```bash
+npx @tanstack/cli create my-app --add-ons clerk -y
+```
+
+Exclusive categories permit only one active choice, so multi-select commands can drop or replace intended providers.
+
+Source: packages/create/src/frameworks/*/*/info.json
+
+### CRITICAL Assume router-only supports deployment integration
+
+Wrong:
+```bash
+npx @tanstack/cli create my-app --router-only --deployment cloudflare -y
+```
+
+Correct:
+```bash
+npx @tanstack/cli create my-app --router-only -y
+```
+
+Router-only mode ignores deployment integration, so the command succeeds without applying the intended ecosystem target.
+
+Source: packages/cli/src/command-line.ts:349
+
+### HIGH Tension: Compatibility mode vs explicit intent
+
+This domain's patterns conflict with create-app-scaffold. Integration planning tends to over-assume command intent is preserved, but compatibility mode silently strips integration flags.
+
+See also: create-app-scaffold/SKILL.md § Common Mistakes
+
+### HIGH Tension: Single-command convenience vs integration precision
+
+This domain's patterns conflict with query-docs-library-metadata. Integration choices tend to drift when discovery metadata is skipped in favor of one-shot scaffold commands.
+
+See also: query-docs-library-metadata/SKILL.md § Common Mistakes
+
+## References
+
+- [Authentication providers](references/authentication-providers.md)
+- [Data layer providers](references/data-layer-providers.md)
+- [Deployment targets](references/deployment-targets.md)

package/skills/choose-ecosystem-integrations/references/authentication-providers.md

@@ -0,0 +1,19 @@
+# Authentication Providers
+
+Use `tanstack ecosystem --category authentication --json` for partner discovery, then map to installable add-on ids via `tanstack create --list-add-ons --json`.
+
+## Common add-ons
+
+- `clerk`
+- `workos`
+- `better-auth`
+
+## Selection pattern
+
+```bash
+npx @tanstack/cli ecosystem --category authentication --json
+npx @tanstack/cli create --list-add-ons --json
+npx @tanstack/cli create my-app --add-ons clerk -y
+```
+
+Authentication providers are typically exclusive; select one unless metadata explicitly allows combination.

package/skills/choose-ecosystem-integrations/references/data-layer-providers.md

@@ -0,0 +1,20 @@
+# Data Layer Providers
+
+Inspect each provider's options before generation to avoid defaulting to an unintended backend.
+
+## Common add-ons
+
+- `prisma`
+- `drizzle`
+- `convex`
+- `neon`
+
+## Selection pattern
+
+```bash
+npx @tanstack/cli create --addon-details prisma --json
+npx @tanstack/cli create --addon-details drizzle --json
+npx @tanstack/cli create my-app --add-ons drizzle -y
+```
+
+Database/ORM categories can be exclusive depending on framework template metadata.

package/skills/choose-ecosystem-integrations/references/deployment-targets.md

@@ -0,0 +1,19 @@
+# Deployment Targets
+
+Map deployment intent to one supported target and include it in scaffold commands only outside router-only mode.
+
+## Common targets
+
+- `cloudflare`
+- `netlify`
+- `railway`
+- `nitro`
+
+## Selection pattern
+
+```bash
+npx @tanstack/cli ecosystem --category deployment --json
+npx @tanstack/cli create my-app --deployment cloudflare -y
+```
+
+Deployment target selection is exclusive and ignored when `--router-only` is active.

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

@@ -0,0 +1,132 @@
+---
+name: create-app-scaffold
+description: >
+  Scaffold a TanStack app with tanstack create using --framework, --template,
+  --toolchain, --deployment, --add-ons, and --router-only. Covers flag
+  compatibility, non-interactive defaults, and intent-preserving command
+  construction.
+type: core
+library: tanstack-cli
+library_version: "0.61.0"
+---
+
+# Create App Scaffold
+
+Use this skill to build a deterministic `tanstack create` command before running generation. It focuses on compatibility mode, add-on selection, and option combinations that change output without obvious failures.
+
+## Setup
+
+```bash
+npx @tanstack/cli create acme-web \
+  --framework react \
+  --toolchain biome \
+  --deployment netlify \
+  --add-ons tanstack-query,clerk \
+  -y
+```
+
+## Core Patterns
+
+### Build a deterministic non-interactive scaffold
+
+```bash
+npx @tanstack/cli create acme-solid \
+  --framework solid \
+  --add-ons drizzle,tanstack-query \
+  --toolchain eslint \
+  -y
+```
+
+### Use router-only mode for compatibility scaffolds only
+
+```bash
+npx @tanstack/cli create legacy-router \
+  --router-only \
+  --framework react \
+  --toolchain biome \
+  -y
+```
+
+### Use template input only outside router-only mode
+
+```bash
+npx @tanstack/cli create custom-app \
+  --framework react \
+  --template https://github.com/acme/tanstack-template \
+  --add-ons tanstack-query \
+  -y
+```
+
+## Common Mistakes
+
+### HIGH Pass --add-ons without explicit ids
+
+Wrong:
+```bash
+npx @tanstack/cli create my-app --add-ons -y
+```
+
+Correct:
+```bash
+npx @tanstack/cli create my-app --add-ons clerk,drizzle -y
+```
+
+In non-interactive runs, empty add-on selection can complete with defaults and silently miss intended integrations. Fixed in newer versions, but agents trained on older examples may still generate this pattern.
+
+Source: https://github.com/TanStack/cli/issues/234
+
+### HIGH Assume --no-tailwind is still supported
+
+Wrong:
+```bash
+npx @tanstack/cli create my-app --no-tailwind -y
+```
+
+Correct:
+```bash
+npx @tanstack/cli create my-app -y
+```
+
+`--no-tailwind` is deprecated and ignored, so output still includes Tailwind and diverges from expected stack constraints.
+
+Source: packages/cli/src/command-line.ts:369
+
+### CRITICAL Combine router-only with template/deployment/add-ons
+
+Wrong:
+```bash
+npx @tanstack/cli create my-app \
+  --router-only \
+  --template some-template \
+  --deployment cloudflare \
+  --add-ons clerk \
+  -y
+```
+
+Correct:
+```bash
+npx @tanstack/cli create my-app --router-only --framework react -y
+```
+
+Router-only compatibility mode ignores template, deployment, and add-on intent, so the command succeeds but produces a materially different scaffold.
+
+Source: packages/cli/src/command-line.ts:343
+
+### HIGH Tension: Compatibility mode vs explicit intent
+
+This domain's patterns conflict with choose-ecosystem-integrations. Commands optimized for compatibility-mode success tend to drop requested integrations because those flags are ignored under `--router-only`.
+
+See also: choose-ecosystem-integrations/SKILL.md § Common Mistakes
+
+### HIGH Tension: Single-command convenience vs integration precision
+
+This domain's patterns conflict with query-docs-library-metadata. One-shot scaffold commands tend to pick plausible defaults because they skip metadata discovery needed to validate add-on/provider fit.
+
+See also: query-docs-library-metadata/SKILL.md § Common Mistakes
+
+## References
+
+- [Create flag compatibility matrix](references/create-flag-compatibility-matrix.md)
+- [Framework adapter options](references/framework-adapters.md)
+- [Deployment provider options](references/deployment-providers.md)
+- [Toolchain options](references/toolchains.md)

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

@@ -0,0 +1,34 @@
+# Create Flag Compatibility Matrix
+
+Targets `@tanstack/cli` v0.61.0.
+
+## Compatibility
+
+| Flag | Works with normal create | Works with `--router-only` | Notes |
+|---|---|---|---|
+| `--framework` | yes | yes | Framework is still honored in both modes. |
+| `--toolchain` | yes | yes | Toolchain selection remains available. |
+| `--add-ons` | yes | no | Ignored in router-only mode. |
+| `--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. |
+
+Source: `packages/cli/src/command-line.ts:337`
+
+## Recommended command construction order
+
+1. Choose mode (`--router-only` or full scaffold).
+2. If full scaffold, resolve add-ons and deployment first.
+3. Add framework and toolchain.
+4. Pass explicit add-on ids and use `-y` only after flags are final.
+
+## Safe presets
+
+```bash
+# Full scaffold preset
+npx @tanstack/cli create app --framework react --add-ons tanstack-query --deployment netlify -y
+
+# Router-only preset
+npx @tanstack/cli create app --router-only --framework react --toolchain biome -y
+```

package/skills/create-app-scaffold/references/deployment-providers.md

@@ -0,0 +1,19 @@
+# Deployment Provider Options
+
+Targets `@tanstack/cli` v0.61.0.
+
+## Common providers
+
+- `cloudflare`
+- `netlify`
+- `railway`
+- `nitro`
+
+## Usage
+
+```bash
+npx @tanstack/cli create app --deployment cloudflare -y
+npx @tanstack/cli create app --deployment netlify -y
+```
+
+Deployment providers are exclusive; choose one per scaffold.

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

@@ -0,0 +1,17 @@
+# Framework Adapter Options
+
+Targets `@tanstack/cli` v0.61.0.
+
+## Supported values
+
+- `react`
+- `solid`
+
+## Usage
+
+```bash
+npx @tanstack/cli create app --framework react -y
+npx @tanstack/cli create app --framework solid -y
+```
+
+Framework selection controls scaffold variant and add-on compatibility surfaces.

package/skills/create-app-scaffold/references/toolchains.md

@@ -0,0 +1,17 @@
+# Toolchain Options
+
+Targets `@tanstack/cli` v0.61.0.
+
+## Supported values
+
+- `eslint`
+- `biome`
+
+## Usage
+
+```bash
+npx @tanstack/cli create app --toolchain eslint -y
+npx @tanstack/cli create app --toolchain biome -y
+```
+
+Toolchain choices are exclusive and affect generated lint configuration.

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

@@ -0,0 +1,118 @@
+---
+name: maintain-custom-addons-dev-watch
+description: >
+  Build and iterate custom add-ons/templates with tanstack add-on init,
+  add-on compile, add-on dev, and tanstack dev --dev-watch, including sync
+  loop preconditions, watch-path validation, and project metadata constraints.
+type: lifecycle
+library: tanstack-cli
+library_version: "0.61.0"
+requires:
+  - add-addons-existing-app
+---
+
+# Maintain Custom Add-ons In Dev Watch
+
+Use this skill for local add-on authoring workflows where you continuously compile and sync package output into a target app.
+
+## Setup
+
+```bash
+npx @tanstack/cli add-on init
+npx @tanstack/cli add-on compile
+```
+
+## Core Patterns
+
+### Run add-on dev loop while editing source
+
+```bash
+npx @tanstack/cli add-on dev
+```
+
+### Sync watched package output into target app
+
+```bash
+npx @tanstack/cli dev --dev-watch ../my-addon-package
+```
+
+### Re-run compile before apply when changing metadata
+
+```bash
+npx @tanstack/cli add-on compile
+npx @tanstack/cli add my-custom-addon
+```
+
+## Common Mistakes
+
+### HIGH Use --dev-watch with --no-install
+
+Wrong:
+```bash
+npx @tanstack/cli dev --dev-watch ../my-addon-package --no-install
+```
+
+Correct:
+```bash
+npx @tanstack/cli dev --dev-watch ../my-addon-package
+```
+
+Dev-watch rejects `--no-install`, so automated loops fail before any sync work starts.
+
+Source: packages/cli/src/dev-watch.ts:112
+
+### HIGH Start dev-watch without valid package entry
+
+Wrong:
+```bash
+npx @tanstack/cli dev --dev-watch ../missing-or-invalid-package
+```
+
+Correct:
+```bash
+npx @tanstack/cli dev --dev-watch ../valid-addon-package
+```
+
+Watch setup validates path and package metadata first, so invalid targets fail before file syncing begins.
+
+Source: packages/cli/src/dev-watch.ts:100
+
+### CRITICAL Author add-on from code-router project
+
+Wrong:
+```bash
+npx @tanstack/cli add-on init
+```
+
+Correct:
+```bash
+# Run add-on init from a file-router project
+npx @tanstack/cli add-on init
+```
+
+Custom add-on authoring expects file-router mode and exits when run from incompatible project modes.
+
+Source: packages/create/src/custom-add-ons/add-on.ts
+
+### HIGH Run add-on workflows without scaffold metadata
+
+Wrong:
+```bash
+npx @tanstack/cli add-on dev
+```
+
+Correct:
+```bash
+# Run in a project scaffolded by TanStack CLI (contains .cta.json), then:
+npx @tanstack/cli add-on dev
+```
+
+Custom add-on flows rely on persisted scaffold options, so missing metadata blocks initialization and update paths.
+
+Source: packages/create/src/custom-add-ons/shared.ts:158
+
+### HIGH Tension: Backwards support vs deterministic automation
+
+This domain's patterns conflict with add-addons-existing-app. Tooling assumes reusable automation, but hidden metadata preconditions from legacy support make add-on loops non-portable across repositories.
+
+See also: add-addons-existing-app/SKILL.md § Common Mistakes