Open History to see the last commit
1# domain_map.yaml
2# Generated by skill-domain-discovery
3# Library: @tanstack/cli
4# Version: 0.62.1
5# Date: 2026-03-06
6# Status: reviewed
7
8library:
9 name: '@tanstack/cli'
10 version: '0.62.1'
11 repository: 'https://github.com/TanStack/cli'
12 description: 'CLI for creating and managing TanStack Start/Router applications, with add-on scaffolding, ecosystem discovery, and custom add-on authoring.'
13 primary_framework: 'framework-agnostic'
14
15domains:
16 - name: 'Scaffolding apps'
17 slug: 'scaffolding'
18 description: 'Creating new TanStack Start/Router projects from scratch with the correct flags, framework, toolchain, and deployment adapter.'
19
20 - name: 'Managing integrations'
21 slug: 'integrations'
22 description: 'Selecting, validating, and applying add-ons — both at project creation time and into existing projects.'
23
24 - name: 'Discovering metadata'
25 slug: 'discovery'
26 description: 'Querying machine-readable CLI output to resolve library ids, add-on ids, partner mappings, and documentation content before code generation.'
27
28 - name: 'Authoring add-ons'
29 slug: 'addon-authoring'
30 description: 'Building, iterating, and publishing custom add-ons and templates using the add-on init/compile/dev workflow and dev-watch sync loop.'
31
32skills:
33 - name: 'Create App Scaffold'
34 slug: 'create-app-scaffold'
35 domain: 'scaffolding'
36 description: 'Build a deterministic tanstack create command — choosing mode, framework, toolchain, deployment, and add-ons with correct flag combinations.'
37 type: core
38 packages:
39 - '@tanstack/cli'
40 covers:
41 - 'tanstack create'
42 - '--framework'
43 - '--toolchain'
44 - '--deployment'
45 - '--add-ons'
46 - '--router-only'
47 - '--template / --starter'
48 - '--no-install / --no-git'
49 - '-y (non-interactive)'
50 - 'validateLegacyCreateFlags'
51 - 'normalizeOptions'
52 tasks:
53 - 'Scaffold a new TanStack Start app with specific integrations'
54 - 'Scaffold a router-only SPA without SSR'
55 - 'Scaffold with a custom or registry template'
56 - 'Run scaffold non-interactively in CI'
57 failure_modes:
58 - mistake: 'Pass --add-ons without explicit ids in non-interactive mode'
59 mechanism: 'Empty --add-ons flag resolves to interactive mode or defaults, silently missing intended integrations.'
60 wrong_pattern: |
61 npx @tanstack/cli create my-app --add-ons -y
62 correct_pattern: |
63 npx @tanstack/cli create my-app --add-ons clerk,drizzle -y
64 source: 'https://github.com/TanStack/cli/issues/234'
65 priority: HIGH
66 status: fixed-but-legacy-risk
67 version_context: 'Fixed in newer versions; agents trained on older examples still generate this.'
68 skills: ['create-app-scaffold']
69
70 - mistake: 'Use deprecated --no-tailwind expecting opt-out to work'
71 mechanism: 'Flag is deprecated and silently ignored; output always includes Tailwind regardless.'
72 wrong_pattern: |
73 npx @tanstack/cli create my-app --no-tailwind -y
74 correct_pattern: |
75 npx @tanstack/cli create my-app -y
76 # Remove Tailwind manually post-scaffold if needed
77 source: 'packages/cli/src/command-line.ts:369'
78 priority: HIGH
79 status: active
80 skills: ['create-app-scaffold']
81
82 - mistake: 'Combine --router-only with add-ons, deployment, or template'
83 mechanism: 'Router-only mode ignores --add-ons, --deployment, --template, and --template-id; command succeeds but produces wrong scaffold.'
84 wrong_pattern: |
85 npx @tanstack/cli create my-app \
86 --router-only \
87 --template some-template \
88 --deployment cloudflare \
89 --add-ons clerk \
90 -y
91 correct_pattern: |
92 npx @tanstack/cli create my-app --router-only --framework react -y
93 source: 'packages/cli/src/command-line.ts:343'
94 priority: CRITICAL
95 status: active
96 skills: ['create-app-scaffold', 'choose-ecosystem-integrations']
97
98 - mistake: 'Use JavaScript/JSX template value'
99 mechanism: 'Templates javascript/js/jsx are explicitly rejected with an error; TanStack Start is TypeScript-only.'
100 wrong_pattern: |
101 npx @tanstack/cli create my-app --template javascript -y
102 correct_pattern: |
103 npx @tanstack/cli create my-app -y
104 source: 'packages/cli/src/command-line.ts:381'
105 priority: HIGH
106 status: active
107 skills: ['create-app-scaffold']
108
109 - name: 'Choose Ecosystem Integrations'
110 slug: 'choose-ecosystem-integrations'
111 domain: 'integrations'
112 description: 'Map user requirements to valid add-on ids using ecosystem and list-add-ons discovery, then compose them correctly respecting exclusive categories and dependency chains.'
113 type: composition
114 packages:
115 - '@tanstack/cli'
116 covers:
117 - 'tanstack ecosystem --json'
118 - 'tanstack create --list-add-ons --json'
119 - 'tanstack create --addon-details --json'
120 - 'exclusive category constraints'
121 - 'dependsOn resolution'
122 - 'add-on options / --add-on-config'
123 tasks:
124 - 'Select auth, database, ORM, and deployment add-ons without conflicts'
125 - 'Inspect per-add-on configuration options before choosing'
126 - 'Map an ecosystem partner name to its installable add-on id'
127 - 'Avoid selecting two add-ons from the same exclusive category'
128 failure_modes:
129 - mistake: 'Use ecosystem partner id directly as add-on id'
130 mechanism: 'Ecosystem partner ids and add-on ids are independent namespaces; partner ids can fail or match the wrong add-on.'
131 wrong_pattern: |
132 npx @tanstack/cli add <partner-id-from-ecosystem-json>
133 correct_pattern: |
134 npx @tanstack/cli ecosystem --json
135 npx @tanstack/cli create --list-add-ons --json
136 # Match partner to add-on id manually, then:
137 npx @tanstack/cli add <mapped-addon-id>
138 source: 'packages/cli/src/cli.ts — ecosystem vs list-add-ons output comparison'
139 priority: HIGH
140 status: active
141 skills: ['choose-ecosystem-integrations', 'add-addons-existing-app']
142
143 - mistake: 'Skip --addon-details before choosing a configurable provider'
144 mechanism: 'Optionized providers silently default (e.g. Prisma defaults to postgres); wrong default locks in the wrong data-layer stack.'
145 wrong_pattern: |
146 npx @tanstack/cli create my-app --add-ons prisma -y
147 correct_pattern: |
148 npx @tanstack/cli create --addon-details prisma --json
149 npx @tanstack/cli create my-app --add-ons prisma --add-on-config '{"prisma":{"provider":"sqlite"}}' -y
150 source: 'packages/create/src/frameworks/react/add-ons/prisma/info.json'
151 priority: HIGH
152 status: active
153 skills: ['choose-ecosystem-integrations']
154
155 - mistake: 'Select multiple add-ons from the same exclusive category'
156 mechanism: 'Exclusive categories (orm, auth, deploy, database, linter) permit only one active choice; multi-select drops or replaces intended providers silently.'
157 wrong_pattern: |
158 npx @tanstack/cli create my-app --add-ons clerk,workos -y
159 correct_pattern: |
160 npx @tanstack/cli create my-app --add-ons clerk -y
161 source: 'packages/create/src/types.ts — AddOnBaseSchema.exclusive'
162 priority: HIGH
163 status: active
164 skills: ['choose-ecosystem-integrations']
165
166 - mistake: 'Assume --router-only supports deployment integration'
167 mechanism: 'Router-only mode ignores --deployment; command succeeds without applying intended deployment target.'
168 wrong_pattern: |
169 npx @tanstack/cli create my-app --router-only --deployment cloudflare -y
170 correct_pattern: |
171 npx @tanstack/cli create my-app --router-only -y
172 source: 'packages/cli/src/command-line.ts:349'
173 priority: CRITICAL
174 status: active
175 skills: ['choose-ecosystem-integrations', 'create-app-scaffold']
176
177 - name: 'Add Add-ons To Existing App'
178 slug: 'add-addons-existing-app'
179 domain: 'integrations'
180 description: 'Layer add-ons into an existing TanStack CLI project using tanstack add, with correct id resolution, dependency handling, and .cta.json precondition checks.'
181 type: core
182 packages:
183 - '@tanstack/cli'
184 covers:
185 - 'tanstack add'
186 - '.cta.json (project config file)'
187 - 'finalizeAddOns — dependency resolution'
188 - 'levenshtein suggestion for typos'
189 - 'remote add-on URLs'
190 tasks:
191 - 'Add one or more add-ons to an existing project'
192 - 'Resolve the correct add-on id before applying'
193 - 'Understand and satisfy add-on dependency requirements'
194 failure_modes:
195 - mistake: 'Run tanstack add outside a TanStack CLI-scaffolded project'
196 mechanism: 'Add flows read .cta.json for persisted scaffold options; missing config causes failure or incomplete application.'
197 wrong_pattern: |
198 # In a project not created with tanstack create:
199 npx @tanstack/cli add clerk
200 correct_pattern: |
201 # Only run in a project with .cta.json (created via tanstack create):
202 npx @tanstack/cli add clerk
203 source: 'packages/create/src/custom-add-ons/shared.ts'
204 priority: CRITICAL
205 status: active
206 skills: ['add-addons-existing-app', 'maintain-custom-addons-dev-watch']
207
208 - mistake: 'Use a misspelled or invalid add-on id'
209 mechanism: 'Unknown ids stop resolution entirely; CLI may suggest the closest match but does not auto-correct.'
210 wrong_pattern: |
211 npx @tanstack/cli add drizle
212 correct_pattern: |
213 npx @tanstack/cli add drizzle
214 source: 'packages/create/src/add-ons.ts:44'
215 priority: HIGH
216 status: active
217 skills: ['add-addons-existing-app']
218
219 - mistake: 'Add an add-on without its required dependencies'
220 mechanism: 'dependsOn is resolved automatically by finalizeAddOns, but remote or custom add-ons may fail if deps are not present.'
221 wrong_pattern: |
222 npx @tanstack/cli add custom-addon-requiring-drizzle
223 correct_pattern: |
224 npx @tanstack/cli create --addon-details custom-addon-requiring-drizzle --json
225 npx @tanstack/cli add drizzle custom-addon-requiring-drizzle
226 source: 'packages/create/src/add-ons.ts:48'
227 priority: HIGH
228 status: active
229 skills: ['add-addons-existing-app']
230
231 - name: 'Query Docs And Library Metadata'
232 slug: 'query-docs-library-metadata'
233 domain: 'discovery'
234 description: 'Retrieve authoritative machine-readable context — library ids, add-on lists, doc pages, and search results — for preflight validation before code generation or integration selection.'
235 type: core
236 packages:
237 - '@tanstack/cli'
238 covers:
239 - 'tanstack libraries --json'
240 - 'tanstack doc <library> <path>'
241 - 'tanstack search-docs --json'
242 - 'tanstack create --list-add-ons --json'
243 - 'tanstack create --addon-details --json'
244 - 'tanstack ecosystem --json'
245 tasks:
246 - 'Resolve valid library ids before fetching docs'
247 - 'Fetch a specific documentation page for code generation context'
248 - 'Search docs for the right guide before implementing a feature'
249 - 'Enumerate available add-ons for an agent planning integrations'
250 reference_candidates:
251 - topic: 'JSON output shapes for all discovery commands'
252 reason: 'Each command has a distinct schema; agents must parse correctly to extract ids, versions, and option surfaces'
253 failure_modes:
254 - mistake: 'Use --library / --version flags on tanstack doc'
255 mechanism: '`doc` takes positional args (<library> <path>), not --library/--version flags; wrong invocation fails with unknown option error.'
256 wrong_pattern: |
257 npx @tanstack/cli doc --library router --version latest --path /docs/framework/react/guide/routing
258 correct_pattern: |
259 npx @tanstack/cli doc router framework/react/guide/routing
260 npx @tanstack/cli doc router framework/react/guide/routing --docs-version latest
261 source: 'packages/cli/src/cli.ts:727'
262 priority: HIGH
263 status: active
264 skills: ['query-docs-library-metadata']
265
266 - mistake: 'Include /docs/ prefix in the doc path argument'
267 mechanism: 'Path argument is appended directly to the docs root; including /docs/ produces a 404-equivalent not-found error.'
268 wrong_pattern: |
269 npx @tanstack/cli doc router /docs/framework/react/guide/routing
270 correct_pattern: |
271 npx @tanstack/cli doc router framework/react/guide/routing
272 source: 'packages/cli/src/cli.ts:765'
273 priority: MEDIUM
274 status: active
275 skills: ['query-docs-library-metadata']
276
277 - mistake: 'Use deprecated create-tsrouter-app alias for discovery'
278 mechanism: 'Legacy alias outputs may not match current CLI discovery behavior; ids and formats differ.'
279 wrong_pattern: |
280 npx create-tsrouter-app --list-add-ons
281 correct_pattern: |
282 npx @tanstack/cli create --list-add-ons --json
283 source: 'https://github.com/TanStack/cli/issues/93'
284 priority: MEDIUM
285 status: fixed-but-legacy-risk
286 version_context: 'Agents trained on older examples may still generate the create-tsrouter-app pattern.'
287 skills: ['query-docs-library-metadata']
288
289 - mistake: 'Treat --list-add-ons --json output as a wrapped object with count key'
290 mechanism: 'Output is a flat JSON array, not an object with a count/addOns wrapper; destructuring the wrong shape silently yields undefined.'
291 wrong_pattern: |
292 # Parsing as: { count, addOns: [] }
293 const { addOns } = JSON.parse(output)
294 correct_pattern: |
295 # Parsing as a flat array:
296 const addOns = JSON.parse(output)
297 source: 'packages/cli/src/cli.ts:268'
298 priority: HIGH
299 status: active
300 skills: ['query-docs-library-metadata']
301
302 - name: 'Maintain Custom Add-ons In Dev Watch'
303 slug: 'maintain-custom-addons-dev-watch'
304 domain: 'addon-authoring'
305 description: 'Build and iterate custom add-ons using tanstack add-on init/compile/dev and the tanstack create --dev-watch sync loop, including preconditions, watch-path validation, and file-router mode requirements.'
306 type: lifecycle
307 packages:
308 - '@tanstack/cli'
309 - '@tanstack/create'
310 covers:
311 - 'tanstack add-on init'
312 - 'tanstack add-on compile'
313 - 'tanstack add-on dev'
314 - 'tanstack create --dev-watch'
315 - '.add-on/ directory structure'
316 - 'add-on.json compiled output'
317 - 'validateAddOnSetup — file-router precondition'
318 - 'validateDevWatchOptions — path validation'
319 - 'DevWatchManager'
320 - 'remote add-on loading via URL'
321 tasks:
322 - 'Initialize a custom add-on from an existing project'
323 - 'Compile add-on assets into a distributable add-on.json'
324 - 'Run a live dev loop while authoring add-on source'
325 - 'Sync a framework directory into a sandbox app for rapid testing'
326 - 'Publish and load a remote add-on via URL'
327 failure_modes:
328 - mistake: 'Run add-on init from a code-router project'
329 mechanism: 'validateAddOnSetup checks project mode and exits with an error if code-router is detected; file-router mode is required.'
330 wrong_pattern: |
331 # In a project created with --code-router:
332 npx @tanstack/cli add-on init
333 correct_pattern: |
334 # In a file-router project (default for TanStack Start):
335 npx @tanstack/cli add-on init
336 source: 'packages/create/src/custom-add-ons/add-on.ts:106'
337 priority: CRITICAL
338 status: active
339 skills: ['maintain-custom-addons-dev-watch']
340
341 - mistake: 'Use --dev-watch on the `dev` subcommand instead of `create`'
342 mechanism: '`--dev-watch` is a flag on `tanstack create`, not on `tanstack dev`; using it on `dev` fails with unknown option.'
343 wrong_pattern: |
344 npx @tanstack/cli dev --dev-watch ../my-framework-dir
345 correct_pattern: |
346 npx @tanstack/cli create my-sandbox --dev-watch ../my-framework-dir
347 source: 'packages/cli/src/cli.ts:511'
348 priority: HIGH
349 status: active
350 skills: ['maintain-custom-addons-dev-watch']
351
352 - mistake: 'Pass --no-install to dev-watch create'
353 mechanism: 'Dev-watch validates options and rejects --no-install; the loop fails before first sync.'
354 wrong_pattern: |
355 npx @tanstack/cli create my-sandbox --dev-watch ../my-framework-dir --no-install
356 correct_pattern: |
357 npx @tanstack/cli create my-sandbox --dev-watch ../my-framework-dir
358 source: 'packages/cli/src/dev-watch.ts'
359 priority: HIGH
360 status: active
361 skills: ['maintain-custom-addons-dev-watch']
362
363 - mistake: 'Point --dev-watch at a path without framework structure'
364 mechanism: 'validateDevWatchOptions checks for add-ons/, assets/, or framework.json; paths missing all three fail validation before sync.'
365 wrong_pattern: |
366 npx @tanstack/cli create my-sandbox --dev-watch ../arbitrary-dir
367 correct_pattern: |
368 npx @tanstack/cli create my-sandbox --dev-watch ../path/with/add-ons-or-assets
369 source: 'packages/cli/src/command-line.ts:599'
370 priority: HIGH
371 status: active
372 skills: ['maintain-custom-addons-dev-watch']
373
374 - mistake: 'Run add-on workflows without .cta.json in working directory'
375 mechanism: 'add-on init/compile/dev read persisted scaffold options from .cta.json; missing config blocks the entire workflow.'
376 wrong_pattern: |
377 # In a project not scaffolded by tanstack create:
378 npx @tanstack/cli add-on dev
379 correct_pattern: |
380 # In a project with .cta.json (created via tanstack create):
381 npx @tanstack/cli add-on dev
382 source: 'packages/create/src/custom-add-ons/shared.ts'
383 priority: HIGH
384 status: active
385 skills: ['maintain-custom-addons-dev-watch', 'add-addons-existing-app']
386
387tensions:
388 - name: 'Compatibility mode vs explicit intent'
389 skills: ['create-app-scaffold', 'choose-ecosystem-integrations']
390 description: '--router-only silently strips add-on, deployment, and template flags that were explicitly requested.'
391 implication: 'An agent optimizing for a working scaffold command will produce --router-only combinations that silently drop integration intent.'
392
393 - name: 'Single-command convenience vs integration precision'
394 skills: ['create-app-scaffold', 'query-docs-library-metadata', 'choose-ecosystem-integrations']
395 description: 'One-shot scaffold commands skip the discovery step needed to validate add-on ids, option defaults, and exclusivity constraints.'
396 implication: 'An agent skipping discovery runs tanstack create with plausible-sounding ids that may be wrong, defaulted incorrectly, or mutually exclusive.'
397
398 - name: 'Automation portability vs scaffold metadata dependency'
399 skills: ['add-addons-existing-app', 'maintain-custom-addons-dev-watch']
400 description: 'Both tanstack add and add-on workflows depend on .cta.json, making them non-portable to projects not created by this CLI.'
401 implication: 'An agent that treats these as general-purpose commands will apply them to arbitrary projects and fail silently or with cryptic errors.'
402
403cross_references:
404 - from: 'create-app-scaffold'
405 to: 'choose-ecosystem-integrations'
406 reason: 'Scaffold flag construction depends on having valid add-on ids, which requires ecosystem/list-add-ons discovery first.'
407
408 - from: 'create-app-scaffold'
409 to: 'query-docs-library-metadata'
410 reason: 'Single-command scaffolds that skip doc discovery tend to pick wrong defaults; reading docs first improves integration choices.'
411
412 - from: 'choose-ecosystem-integrations'
413 to: 'query-docs-library-metadata'
414 reason: 'Partner-to-add-on mapping and option inspection both use --json discovery commands covered in this skill.'
415
416 - from: 'add-addons-existing-app'
417 to: 'choose-ecosystem-integrations'
418 reason: 'Choosing which add-ons to apply requires understanding exclusive categories and dependency chains.'
419
420 - from: 'maintain-custom-addons-dev-watch'
421 to: 'add-addons-existing-app'
422 reason: 'Custom add-on authoring workflow assumes familiarity with add-on application patterns including .cta.json preconditions.'
423
424gaps:
425 - skill: 'create-app-scaffold'
426 question: 'What is the full list of built-in template ids available via --template? The registry URL is configurable via CTA_REGISTRY env var — are there any documented public registries?'
427 context: 'The source resolves template ids from a registry but no public list is documented.'
428 status: open
429
430 - skill: 'maintain-custom-addons-dev-watch'
431 question: 'Is tanstack template init/compile a distinct workflow from add-on init/compile, and if so what are the key differences an agent should know?'
432 context: 'Both commands exist in cli.ts but template authoring has no dedicated skill yet.'
433 status: open