Skip to content
Source
Sign inSign up
TanStack/cli
Open History to see the last commit

domain_map.yaml

284 lines14.4 KB

1# domain_map.yaml
2# Generated by skill-domain-discovery
3# Library: TanStack CLI
4# Version: 0.61.0
5# Date: 2026-03-02
6# Status: reviewed
7​
8library:
9 name: "@tanstack/cli"
10 version: "0.61.0"
11 repository: "https://github.com/TanStack/cli"
12 description: "CLI for scaffolding TanStack apps, adding add-ons, and retrieving machine-readable TanStack/ecosystem context."
13 primary_framework: "framework-agnostic"
14​
15domains:
16 - name: "Scaffold new applications"
17 slug: "scaffold-new-applications"
18 description: "Choosing mode/framework/template/add-ons/toolchain/deployment and generating the initial project."
19 - name: "Evolve existing applications"
20 slug: "evolve-existing-applications"
21 description: "Applying add-ons to an existing repo while preserving and extending current project structure."
22 - name: "Fetch support context for agents"
23 slug: "fetch-support-context"
24 description: "Using CLI discovery/doc commands to retrieve structured context for support and coding agents."
25 - name: "Select ecosystem integrations"
26 slug: "select-ecosystem-integrations"
27 description: "Translating ecosystem partner data and add-on metadata into concrete integration choices."
28 - name: "Author and iterate custom extensions"
29 slug: "author-custom-extensions"
30 description: "Building and live-iterating custom add-ons/templates and syncing generated outputs during development."
31​
32skills:
33 - name: "Create app scaffold"
34 slug: "create-app-scaffold"
35 domain: "scaffold-new-applications"
36 description: "Scaffold a new app with the right mode/framework/template/toolchain/deployment/add-on combination."
37 type: "core"
38 covers:
39 - "tanstack create"
40 - "--framework"
41 - "--template / --template-id"
42 - "--toolchain"
43 - "--deployment"
44 - "--add-ons"
45 - "--router-only"
46 tasks:
47 - "Create a React or Solid app with selected add-ons"
48 - "Create router-only compatibility scaffold"
49 - "Generate app from local or remote template"
50 subsystems:
51 - name: "Framework adapters"
52 package: "@tanstack/create"
53 config_surface: "framework id (react/solid) and mode compatibility"
54 - name: "Deployment providers"
55 package: "@tanstack/create"
56 config_surface: "exclusive deploy add-ons (cloudflare/netlify/railway/nitro)"
57 - name: "Toolchains"
58 package: "@tanstack/create"
59 config_surface: "exclusive linter choice (eslint/biome)"
60 reference_candidates:
61 - topic: "create flag compatibility matrix"
62 reason: "Many interacting flags and compatibility branches (router-only/template/add-ons/deployment/toolchain)."
63 failure_modes:
64 - mistake: "Pass --add-ons without explicit ids"
65 mechanism: "In non-interactive runs this can complete without selecting add-ons, so output differs from user intent."
66 source: "https://github.com/TanStack/cli/issues/234"
67 priority: "HIGH"
68 status: "fixed-but-legacy-risk"
69 version_context: "Observed in older releases and still generated by agents trained on older examples."
70 - mistake: "Assume --no-tailwind is still supported"
71 mechanism: "Tailwind opt-out flags are deprecated/ignored, so generated scaffold still includes Tailwind and requires manual cleanup."
72 source: "packages/cli/src/command-line.ts"
73 priority: "HIGH"
74 status: "active"
75 version_context: "Current behavior; maintainers recommend scaffold then remove Tailwind manually."
76 - mistake: "Combine router-only with template/deployment/add-ons"
77 mechanism: "Router-only compatibility mode silently ignores template, deployment, and add-on intents and proceeds with base scaffold."
78 source: "packages/cli/src/command-line.ts"
79 priority: "CRITICAL"
80 status: "active"
81 version_context: "Current behavior; maintainer preference is proceed and explicitly drop incompatible intents."
82 skills: ["create-app-scaffold", "choose-ecosystem-integrations"]
83 compositions:
84 - library: "Cloudflare"
85 skill: "choose-ecosystem-integrations"
86 - library: "Netlify"
87 skill: "choose-ecosystem-integrations"
88 - library: "Railway"
89 skill: "choose-ecosystem-integrations"
90​
91 - name: "Add add-ons to existing app"
92 slug: "add-addons-existing-app"
93 domain: "evolve-existing-applications"
94 description: "Apply one or more add-ons to an existing project and reconcile file/package changes."
95 type: "core"
96 covers:
97 - "tanstack add"
98 - "@tanstack/create addToApp"
99 - ".cta.json persisted project options"
100 - "add-on dependency resolution"
101 tasks:
102 - "Add auth/database/tooling add-ons to an existing app"
103 - "Resolve add-on dependency chains"
104 - "Handle add-on option defaults and prompts"
105 failure_modes:
106 - mistake: "Run tanstack add without .cta.json"
107 mechanism: "Older or non-CLI projects fail because persisted scaffold metadata is required to reconstruct options."
108 source: "packages/create/src/custom-add-ons/shared.ts"
109 priority: "CRITICAL"
110 status: "active"
111 version_context: "Still supported for now but likely to be replaced by skills/playbook-led approach (maintainer interview)."
112 skills: ["add-addons-existing-app", "maintain-custom-addons-dev-watch"]
113 - mistake: "Use invalid add-on id"
114 mechanism: "Resolution throws add-on not found (with suggestion), blocking apply flow until corrected id is provided."
115 source: "packages/create/src/add-ons.ts"
116 priority: "HIGH"
117 status: "active"
118 version_context: "Current behavior."
119 - mistake: "Ignore add-on dependency requirements"
120 mechanism: "Selecting add-ons without required dependencies can trigger dependency-not-found failures during finalization."
121 source: "packages/create/src/add-ons.ts"
122 priority: "HIGH"
123 status: "active"
124 version_context: "Current behavior; common with custom/remote add-ons."
125 - mistake: "Assume old Windows path bug still present"
126 mechanism: "Agents may avoid tanstack add on Windows due to old path resolution failures that were fixed in later versions."
127 source: "https://github.com/TanStack/cli/issues/329"
128 priority: "MEDIUM"
129 status: "fixed-but-legacy-risk"
130 version_context: "Fixed after issue #329; older snippets still circulate."
131 compositions:
132 - library: "Clerk"
133 skill: "choose-ecosystem-integrations"
134 - library: "Drizzle"
135 skill: "choose-ecosystem-integrations"
136 - library: "Prisma"
137 skill: "choose-ecosystem-integrations"
138​
139 - name: "Query docs and library metadata"
140 slug: "query-docs-library-metadata"
141 domain: "fetch-support-context"
142 description: "Use CLI discovery commands to retrieve machine-readable TanStack docs/library information for agents and support."
143 type: "core"
144 covers:
145 - "tanstack libraries --json"
146 - "tanstack doc"
147 - "tanstack search-docs --json"
148 - "tanstack create --list-add-ons --json"
149 - "tanstack create --addon-details --json"
150 tasks:
151 - "Enumerate TanStack libraries and versions"
152 - "Fetch a specific docs page in markdown"
153 - "Search docs for a targeted implementation topic"
154 reference_candidates:
155 - topic: "discovery command output schemas"
156 reason: "Multiple JSON payload shapes consumed by agents (libraries, docs pages, search hits, add-on metadata)."
157 failure_modes:
158 - mistake: "Use removed tanstack mcp command"
159 mechanism: "Command no longer exists, so agent setup scripts based on older docs fail and provide no tools."
160 source: "packages/cli/CHANGELOG.md"
161 priority: "CRITICAL"
162 status: "removed"
163 version_context: "Removed in v0.52.0; legacy examples still appear in historical threads."
164 - mistake: "Use invalid library id/version/path for doc fetch"
165 mechanism: "doc command throws explicit not-found errors when id/version/path does not match registry metadata."
166 source: "packages/cli/src/cli.ts"
167 priority: "HIGH"
168 status: "active"
169 version_context: "Current behavior."
170 - mistake: "Rely on deprecated create alias for discovery"
171 mechanism: "Older alias-based invocations (eg create-tsrouter-app --list-add-ons) have produced confusing or empty outputs."
172 source: "https://github.com/TanStack/cli/issues/93"
173 priority: "MEDIUM"
174 status: "fixed-but-legacy-risk"
175 version_context: "Resolved, but agent corpora still include old alias patterns."
176​
177 - name: "Choose ecosystem integrations"
178 slug: "choose-ecosystem-integrations"
179 domain: "select-ecosystem-integrations"
180 description: "Use ecosystem and add-on metadata to choose compatible auth/database/deployment/tooling integrations for a target scaffold."
181 type: "composition"
182 covers:
183 - "tanstack ecosystem --json"
184 - "tanstack create --list-add-ons --json"
185 - "tanstack create --addon-details <id> --json"
186 - "add-on category/exclusive/dependsOn/option surfaces"
187 tasks:
188 - "Map user requirements to candidate ecosystem partners"
189 - "Translate partner choice to concrete add-on ids"
190 - "Resolve exclusive categories and option prompts before create/add"
191 subsystems:
192 - name: "Authentication providers"
193 package: "@tanstack/create"
194 config_surface: "exclusive auth add-ons (clerk/workos/better-auth)"
195 - name: "Data layer providers"
196 package: "@tanstack/create"
197 config_surface: "database/orm exclusivity and optionized providers (prisma/drizzle/convex/neon)"
198 - name: "Deployment targets"
199 package: "@tanstack/create"
200 config_surface: "exclusive deploy target selection"
201 failure_modes:
202 - mistake: "Treat ecosystem partner id as add-on id"
203 mechanism: "ecosystem output includes partners not installable as CLI add-ons, leading to add-on-not-found errors later."
204 source: "tanstack ecosystem --json output + tanstack create --list-add-ons --json output"
205 priority: "HIGH"
206 status: "active"
207 version_context: "Current behavior; requires explicit mapping step."
208 - mistake: "Skip addon-details before choosing provider"
209 mechanism: "Optionized add-ons (eg prisma/drizzle database provider) default silently, producing wrong DB stack for the intended integration."
210 source: "tanstack create --addon-details prisma --json"
211 priority: "HIGH"
212 status: "active"
213 version_context: "Current behavior with option defaults."
214 - mistake: "Select multiple exclusive integrations together"
215 mechanism: "Combining providers from exclusive categories causes one choice to be dropped/replaced, diverging from explicit intent."
216 source: "packages/create/src/frameworks/*/*/info.json"
217 priority: "HIGH"
218 status: "active"
219 version_context: "Current add-on metadata model uses exclusive categories."
220 - mistake: "Assume router-only supports deployment integration"
221 mechanism: "In router-only compatibility mode deployment intent is ignored, so ecosystem choice never lands in generated output."
222 source: "packages/cli/src/command-line.ts"
223 priority: "CRITICAL"
224 status: "active"
225 version_context: "Current behavior."
226 skills: ["choose-ecosystem-integrations", "create-app-scaffold"]
227​
228 - name: "Maintain custom add-ons in dev watch"
229 slug: "maintain-custom-addons-dev-watch"
230 domain: "author-custom-extensions"
231 description: "Initialize, compile, and live-watch custom add-ons/templates while syncing generated assets into a target app."
232 type: "lifecycle"
233 covers:
234 - "tanstack add-on init"
235 - "tanstack add-on compile"
236 - "tanstack add-on dev"
237 - "tanstack dev --dev-watch"
238 - "FileSyncer sync/delete behavior"
239 tasks:
240 - "Bootstrap custom add-on metadata and compiled output"
241 - "Run continuous add-on rebuild while editing source files"
242 - "Sync watched package output into local target app"
243 failure_modes:
244 - mistake: "Use --dev-watch with --no-install"
245 mechanism: "The command throws because dev watch requires installation to validate and execute watched package output."
246 source: "packages/cli/src/dev-watch.ts"
247 priority: "HIGH"
248 status: "active"
249 version_context: "Current behavior."
250 - mistake: "Start dev-watch without valid package entry"
251 mechanism: "Missing watch path/package.json/entrypoint fails early with setup errors before sync loop starts."
252 source: "packages/cli/src/dev-watch.ts"
253 priority: "HIGH"
254 status: "active"
255 version_context: "Current behavior."
256 - mistake: "Author add-on from code-router project"
257 mechanism: "Custom add-on init exits because add-on authoring expects file-router project mode."
258 source: "packages/create/src/custom-add-ons/add-on.ts"
259 priority: "CRITICAL"
260 status: "active"
261 version_context: "Current behavior."
262 - mistake: "Run add-on workflows without scaffold metadata"
263 mechanism: "Custom add-on/template workflows depend on .cta.json and fail in projects lacking persisted options."
264 source: "packages/create/src/custom-add-ons/shared.ts"
265 priority: "HIGH"
266 status: "active"
267 version_context: "Current behavior; may be replaced in future architecture."
268 skills: ["maintain-custom-addons-dev-watch", "add-addons-existing-app"]
269​
270tensions:
271 - name: "Compatibility mode vs explicit intent"
272 skills: ["create-app-scaffold", "choose-ecosystem-integrations"]
273 description: "Router-only compatibility keeps legacy flows easy but silently drops template/deployment/add-on intent."
274 implication: "Agents optimize for command success and miss that requested integrations were never applied."
275 - name: "Backwards support vs deterministic automation"
276 skills: ["add-addons-existing-app", "maintain-custom-addons-dev-watch"]
277 description: "Legacy .cta.json-based support helps old projects but creates hidden preconditions for automation."
278 implication: "Agents assume add/author flows are universal and fail when metadata preconditions are absent."
279 - name: "Single-command convenience vs integration precision"
280 skills: ["create-app-scaffold", "query-docs-library-metadata", "choose-ecosystem-integrations"]
281 description: "Fast scaffolding encourages one-shot commands, while robust integration requires preflight metadata discovery."
282 implication: "Agents skip discovery and produce plausible defaults that do not match user architecture constraints."
283​
284gaps: []