@tanstack/cli 0.60.1 → 0.62.0

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

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

@@ -0,0 +1,85 @@
+---
+name: query-docs-library-metadata
+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.61.0"
+---
+
+# Query Docs And Library Metadata
+
+Use this skill to collect authoritative context before code generation or integration selection.
+
+## Setup
+
+```bash
+npx @tanstack/cli libraries --json
+```
+
+## Core Patterns
+
+### Resolve valid library ids before doc fetch
+
+```bash
+npx @tanstack/cli libraries --json
+```
+
+### Fetch a specific docs page with explicit version
+
+```bash
+npx @tanstack/cli doc --library router --version latest --path /docs/framework/react/guide/routing
+```
+
+### Search docs for implementation targets
+
+```bash
+npx @tanstack/cli search-docs "server functions" --library start --json
+```
+
+## Common Mistakes
+
+### HIGH Use invalid library id/version/path for doc fetch
+
+Wrong:
+```bash
+npx @tanstack/cli doc --library made-up-lib --version latest --path /docs
+```
+
+Correct:
+```bash
+npx @tanstack/cli libraries --json
+npx @tanstack/cli doc --library router --version latest --path /docs/framework/react/guide/routing
+```
+
+`doc` validates identifiers against registry metadata and fails when any segment is not real.
+
+Source: packages/cli/src/cli.ts:746
+
+### MEDIUM Rely on deprecated create alias for discovery
+
+Wrong:
+```bash
+npx create-tsrouter-app --list-add-ons
+```
+
+Correct:
+```bash
+npx @tanstack/cli create --list-add-ons --json
+```
+
+Legacy alias workflows can produce confusing outputs that do not match current CLI discovery behavior. Fixed in newer versions, but agents trained on older examples may still generate this pattern.
+
+Source: https://github.com/TanStack/cli/issues/93
+
+### HIGH Tension: Single-command convenience vs integration precision
+
+This domain's patterns conflict with create-app-scaffold and choose-ecosystem-integrations. Skipping discovery to run one-shot scaffold commands tends to lock in plausible defaults that miss architecture constraints.
+
+See also: create-app-scaffold/SKILL.md § Common Mistakes
+
+## References
+
+- [Discovery command output schemas](references/discovery-command-output-schemas.md)

package/skills/query-docs-library-metadata/references/discovery-command-output-schemas.md

@@ -0,0 +1,70 @@
+# Discovery Command Output Schemas
+
+Targets `@tanstack/cli` v0.61.0.
+
+## `tanstack libraries --json`
+
+```json
+{
+  "count": 3,
+  "libraries": [
+    {
+      "id": "router",
+      "label": "TanStack Router",
+      "description": "Type-safe routing",
+      "latestVersion": "latest"
+    }
+  ]
+}
+```
+
+## `tanstack search-docs <query> --json`
+
+```json
+{
+  "query": "server functions",
+  "results": [
+    {
+      "library": "start",
+      "version": "latest",
+      "title": "Server Functions",
+      "path": "/docs/framework/react/guide/server-functions"
+    }
+  ]
+}
+```
+
+## `tanstack create --list-add-ons --json`
+
+```json
+{
+  "count": 4,
+  "addOns": [
+    {
+      "id": "drizzle",
+      "name": "Drizzle",
+      "category": "database",
+      "dependsOn": []
+    }
+  ]
+}
+```
+
+## `tanstack create --addon-details <id> --json`
+
+```json
+{
+  "id": "prisma",
+  "name": "Prisma",
+  "options": [
+    {
+      "name": "provider",
+      "default": "postgres",
+      "choices": ["postgres", "sqlite", "mysql"]
+    }
+  ],
+  "dependsOn": []
+}
+```
+
+Use this reference to parse shapes defensively and normalize fields before feeding downstream planning or generation steps.