@tanstack/cli 0.60.1 → 0.62.0

package/dist/options.js

@@ -1,6 +1,7 @@
 import { intro } from '@clack/prompts';
-import { finalizeAddOns, getFrameworkById, getPackageManager, populateAddOnOptionsDefaults, readConfigFile, } from '@tanstack/create';
-import { getProjectName, promptForAddOnOptions, promptForEnvVars, selectAddOns, selectDeployment, selectExamples, selectGit, selectPackageManager, selectToolchain, } from './ui-prompts.js';
+import { finalizeAddOns, getFrameworkById, getPackageManager, loadStarter, populateAddOnOptionsDefaults, readConfigFile, } from '@tanstack/create';
+import { getProjectName, promptForAddOnOptions, promptForEnvVars, selectAddOns, selectDeployment, selectExamples, selectGit, selectPackageManager, selectTemplate, selectToolchain, } from './ui-prompts.js';
+import { listTemplateChoices, resolveStarterSpecifier, } from './command-line.js';
 import { getCurrentDirectoryName, sanitizePackageName, validateProjectName, } from './utils.js';
 export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], showDeploymentOptions = false, }) {
     const options = {};
@@ -30,6 +31,32 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], sh
         ['file-router', 'typescript', 'tsx', 'javascript', 'js', 'jsx'].includes(template);
     const routerOnly = !!cliOptions.routerOnly ||
         (isLegacyTemplate ? template !== 'file-router' : false);
+    if (!cliOptions.starter) {
+        if (cliOptions.template && !isLegacyTemplate) {
+            cliOptions.starter = cliOptions.template;
+        }
+        else if (cliOptions.templateId) {
+            cliOptions.starter = cliOptions.templateId;
+        }
+    }
+    if (!routerOnly && !cliOptions.starter) {
+        const starterChoices = await listTemplateChoices(options.framework.id);
+        const selectedTemplateId = await selectTemplate(starterChoices.map((choice) => ({
+            id: choice.id,
+            name: choice.name,
+            description: choice.description,
+        })));
+        if (selectedTemplateId) {
+            cliOptions.starter = selectedTemplateId;
+        }
+    }
+    const starter = !routerOnly && cliOptions.starter
+        ? await loadStarter(await resolveStarterSpecifier(cliOptions.starter, options.framework.id))
+        : undefined;
+    if (starter) {
+        options.framework = getFrameworkById(starter.framework) || options.framework;
+        options.mode = starter.mode;
+    }
     // TypeScript is always enabled with file-router
     options.typescript = true;
     // Package manager selection
@@ -62,6 +89,9 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], sh
         addOns.add(deployment);
     }
     if (!routerOnly) {
+        for (const addOn of starter?.dependsOn || []) {
+            addOns.add(addOn);
+        }
         for (const addOn of forcedAddOns) {
             addOns.add(addOn);
         }
@@ -112,6 +142,9 @@ export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], sh
     if (cliOptions.install === false) {
         options.install = false;
     }
+    if (starter) {
+        options.starter = starter;
+    }
     return options;
 }
 export async function promptForAddOns() {

package/dist/types/command-line.d.ts

@@ -1,5 +1,12 @@
 import type { Options } from '@tanstack/create';
 import type { CliOptions } from './types.js';
+export declare function resolveStarterSpecifier(starterSpecifier: string, preferredFramework?: string): Promise<string>;
+export declare function listTemplateChoices(preferredFramework?: string): Promise<Array<{
+    id: string;
+    name: string;
+    description?: string;
+    framework: string;
+}>>;
 export declare function validateLegacyCreateFlags(cliOptions: CliOptions): {
     warnings: Array<string>;
     error?: string;

package/dist/types/{mcp/types.d.ts → discovery.d.ts}

@@ -1,48 +1,5 @@
 import { z } from 'zod';
-export declare const LibrarySchema: z.ZodObject<{
-    id: z.ZodString;
-    name: z.ZodString;
-    tagline: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    frameworks: z.ZodArray<z.ZodString, "many">;
-    latestVersion: z.ZodString;
-    latestBranch: z.ZodOptional<z.ZodString>;
-    availableVersions: z.ZodArray<z.ZodString, "many">;
-    repo: z.ZodString;
-    docsRoot: z.ZodOptional<z.ZodString>;
-    defaultDocs: z.ZodOptional<z.ZodString>;
-    docsUrl: z.ZodOptional<z.ZodString>;
-    githubUrl: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    id: string;
-    name: string;
-    tagline: string;
-    frameworks: string[];
-    latestVersion: string;
-    availableVersions: string[];
-    repo: string;
-    description?: string | undefined;
-    latestBranch?: string | undefined;
-    docsRoot?: string | undefined;
-    defaultDocs?: string | undefined;
-    docsUrl?: string | undefined;
-    githubUrl?: string | undefined;
-}, {
-    id: string;
-    name: string;
-    tagline: string;
-    frameworks: string[];
-    latestVersion: string;
-    availableVersions: string[];
-    repo: string;
-    description?: string | undefined;
-    latestBranch?: string | undefined;
-    docsRoot?: string | undefined;
-    defaultDocs?: string | undefined;
-    docsUrl?: string | undefined;
-    githubUrl?: string | undefined;
-}>;
-export declare const LibrariesResponseSchema: z.ZodObject<{
+declare const LibrariesResponseSchema: z.ZodObject<{
     libraries: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
@@ -125,35 +82,7 @@ export declare const LibrariesResponseSchema: z.ZodObject<{
     groups: Record<string, string[]>;
     groupNames: Record<string, string>;
 }>;
-export declare const PartnerSchema: z.ZodObject<{
-    id: z.ZodString;
-    name: z.ZodString;
-    tagline: z.ZodOptional<z.ZodString>;
-    description: z.ZodString;
-    category: z.ZodString;
-    categoryLabel: z.ZodString;
-    libraries: z.ZodArray<z.ZodString, "many">;
-    url: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    id: string;
-    name: string;
-    description: string;
-    libraries: string[];
-    category: string;
-    categoryLabel: string;
-    url: string;
-    tagline?: string | undefined;
-}, {
-    id: string;
-    name: string;
-    description: string;
-    libraries: string[];
-    category: string;
-    categoryLabel: string;
-    url: string;
-    tagline?: string | undefined;
-}>;
-export declare const PartnersResponseSchema: z.ZodObject<{
+declare const PartnersResponseSchema: z.ZodObject<{
     partners: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
@@ -211,7 +140,26 @@ export declare const PartnersResponseSchema: z.ZodObject<{
     categories: string[];
     categoryLabels: Record<string, string>;
 }>;
-export type Library = z.infer<typeof LibrarySchema>;
+export declare const LIBRARY_GROUPS: readonly ["state", "headlessUI", "performance", "tooling"];
 export type LibrariesResponse = z.infer<typeof LibrariesResponseSchema>;
-export type Partner = z.infer<typeof PartnerSchema>;
 export type PartnersResponse = z.infer<typeof PartnersResponseSchema>;
+export declare function fetchLibraries(): Promise<LibrariesResponse>;
+export declare function fetchPartners(): Promise<PartnersResponse>;
+export declare function fetchDocContent(repo: string, branch: string, filePath: string): Promise<string | null>;
+export declare function searchTanStackDocs({ query, library, framework, limit, }: {
+    query: string;
+    library?: string;
+    framework?: string;
+    limit?: number;
+}): Promise<{
+    query: string;
+    totalHits: number;
+    results: Array<{
+        title: string;
+        url: string;
+        snippet: string;
+        library: string;
+        breadcrumb: Array<string>;
+    }>;
+}>;
+export {};

package/dist/types/types.d.ts

@@ -9,8 +9,7 @@ export interface CliOptions {
     addOns?: Array<string> | boolean;
     listAddOns?: boolean;
     addonDetails?: string;
-    mcp?: boolean;
-    mcpSse?: boolean;
+    json?: boolean;
     starter?: string;
     templateId?: string;
     targetDir?: string;

package/dist/types/ui-prompts.d.ts

@@ -2,6 +2,11 @@ import type { AddOn, PackageManager } from '@tanstack/create';
 import type { Framework } from '@tanstack/create/dist/types/types.js';
 export declare function getProjectName(): Promise<string>;
 export declare function selectPackageManager(): Promise<PackageManager>;
+export declare function selectTemplate(templates: Array<{
+    id: string;
+    name: string;
+    description?: string;
+}>): Promise<string | undefined>;
 export declare function selectAddOns(framework: Framework, mode: string, type: string, message: string, forcedAddOns?: Array<string>, allowMultiple?: boolean): Promise<Array<string>>;
 export declare function selectGit(): Promise<boolean>;
 export declare function selectExamples(): Promise<boolean>;

package/dist/ui-prompts.js

@@ -36,6 +36,32 @@ export async function selectPackageManager() {
     }
     return packageManager;
 }
+export async function selectTemplate(templates) {
+    if (templates.length === 0) {
+        return undefined;
+    }
+    const selected = await select({
+        message: 'Would you like to start from a template?',
+        options: [
+            {
+                value: undefined,
+                label: 'None (base starter)',
+                hint: 'Two-page baseline (Home + About)',
+            },
+            ...templates.map((template) => ({
+                value: template.id,
+                label: template.name,
+                hint: template.description,
+            })),
+        ],
+        initialValue: undefined,
+    });
+    if (isCancel(selected)) {
+        cancel('Operation cancelled.');
+        process.exit(0);
+    }
+    return selected;
+}
 // Track if we've shown the multiselect help text
 let hasShownMultiselectHelp = false;
 export async function selectAddOns(framework, mode, type, message, forcedAddOns = [], allowMultiple = true) {

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@tanstack/cli",
-  "version": "0.60.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"
   },
@@ -28,23 +32,20 @@
   "license": "MIT",
   "dependencies": {
     "@clack/prompts": "^0.10.0",
-    "@modelcontextprotocol/sdk": "^1.6.0",
     "chalk": "^5.4.1",
     "chokidar": "^3.6.0",
     "commander": "^13.1.0",
     "diff": "^7.0.0",
-    "express": "^4.21.2",
     "semver": "^7.7.2",
     "tempy": "^3.1.0",
     "validate-npm-package-name": "^7.0.0",
     "zod": "^3.24.2",
-    "@tanstack/create": "0.62.1"
+    "@tanstack/create": "0.62.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",
     "@tanstack/config": "^0.16.2",
     "@types/diff": "^5.2.0",
-    "@types/express": "^5.0.1",
     "@types/node": "^22.13.4",
     "@types/semver": "^7.7.0",
     "@types/validate-npm-package-name": "^4.0.2",

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.