@tanstack/cli 0.60.1 → 0.61.1

package/src/discovery.ts

@@ -0,0 +1,209 @@
+import { z } from 'zod'
+
+const TANSTACK_API_BASE = 'https://tanstack.com/api/data'
+
+const LibrarySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  tagline: z.string(),
+  description: z.string().optional(),
+  frameworks: z.array(z.string()),
+  latestVersion: z.string(),
+  latestBranch: z.string().optional(),
+  availableVersions: z.array(z.string()),
+  repo: z.string(),
+  docsRoot: z.string().optional(),
+  defaultDocs: z.string().optional(),
+  docsUrl: z.string().optional(),
+  githubUrl: z.string().optional(),
+})
+
+const LibrariesResponseSchema = z.object({
+  libraries: z.array(LibrarySchema),
+  groups: z.record(z.array(z.string())),
+  groupNames: z.record(z.string()),
+})
+
+const PartnerSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  tagline: z.string().optional(),
+  description: z.string(),
+  category: z.string(),
+  categoryLabel: z.string(),
+  libraries: z.array(z.string()),
+  url: z.string(),
+})
+
+const PartnersResponseSchema = z.object({
+  partners: z.array(PartnerSchema),
+  categories: z.array(z.string()),
+  categoryLabels: z.record(z.string()),
+})
+
+export const LIBRARY_GROUPS = ['state', 'headlessUI', 'performance', 'tooling'] as const
+
+// Algolia config (public read-only keys)
+const ALGOLIA_APP_ID = 'FQ0DQ6MA3C'
+const ALGOLIA_API_KEY = '10c34d6a5c89f6048cf644d601e65172'
+const ALGOLIA_INDEX = 'tanstack-test'
+
+export type LibrariesResponse = z.infer<typeof LibrariesResponseSchema>
+export type PartnersResponse = z.infer<typeof PartnersResponseSchema>
+
+export async function fetchLibraries(): Promise<LibrariesResponse> {
+  const response = await fetch(`${TANSTACK_API_BASE}/libraries`)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch libraries: ${response.statusText}`)
+  }
+  const data = await response.json()
+  return LibrariesResponseSchema.parse(data)
+}
+
+export async function fetchPartners(): Promise<PartnersResponse> {
+  const response = await fetch(`${TANSTACK_API_BASE}/partners`)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch partners: ${response.statusText}`)
+  }
+  const data = await response.json()
+  return PartnersResponseSchema.parse(data)
+}
+
+export async function fetchDocContent(
+  repo: string,
+  branch: string,
+  filePath: string,
+): Promise<string | null> {
+  const url = `https://raw.githubusercontent.com/${repo}/${branch}/${filePath}`
+  const response = await fetch(url, {
+    headers: { 'User-Agent': 'tanstack-cli' },
+  })
+
+  if (!response.ok) {
+    if (response.status === 404) {
+      return null
+    }
+    throw new Error(`Failed to fetch doc: ${response.statusText}`)
+  }
+
+  return response.text()
+}
+
+export async function searchTanStackDocs({
+  query,
+  library,
+  framework,
+  limit = 10,
+}: {
+  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>
+  }>
+}> {
+  const ALL_LIBRARIES = [
+    'config',
+    'form',
+    'optimistic',
+    'pacer',
+    'query',
+    'ranger',
+    'react-charts',
+    'router',
+    'start',
+    'store',
+    'table',
+    'virtual',
+    'db',
+    'devtools',
+  ]
+  const ALL_FRAMEWORKS = ['react', 'vue', 'solid', 'svelte', 'angular']
+
+  const filterParts: Array<string> = ['version:latest']
+
+  if (library) {
+    const otherLibraries = ALL_LIBRARIES.filter((l) => l !== library)
+    const exclusions = otherLibraries.map((l) => `NOT library:${l}`).join(' AND ')
+    if (exclusions) filterParts.push(`(${exclusions})`)
+  }
+
+  if (framework) {
+    const otherFrameworks = ALL_FRAMEWORKS.filter((f) => f !== framework)
+    const exclusions = otherFrameworks.map((f) => `NOT framework:${f}`).join(' AND ')
+    if (exclusions) filterParts.push(`(${exclusions})`)
+  }
+
+  const searchParams = {
+    requests: [
+      {
+        indexName: ALGOLIA_INDEX,
+        query,
+        hitsPerPage: Math.min(limit, 50),
+        filters: filterParts.join(' AND '),
+        attributesToRetrieve: ['hierarchy', 'url', 'content', 'library'],
+        attributesToSnippet: ['content:80'],
+      },
+    ],
+  }
+
+  const response = await fetch(
+    `https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes/*/queries`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Algolia-Application-Id': ALGOLIA_APP_ID,
+        'X-Algolia-API-Key': ALGOLIA_API_KEY,
+      },
+      body: JSON.stringify(searchParams),
+    },
+  )
+
+  if (!response.ok) {
+    throw new Error(`Algolia search failed: ${response.statusText}`)
+  }
+
+  const searchResponse = (await response.json()) as {
+    results: Array<{
+      hits: Array<{
+        objectID: string
+        url: string
+        library?: string
+        hierarchy: Record<string, string | undefined>
+        content?: string
+        _snippetResult?: { content?: { value?: string } }
+      }>
+      nbHits?: number
+    }>
+  }
+
+  const searchResult = searchResponse.results[0]
+
+  const results = searchResult.hits.map((hit) => {
+    const breadcrumb = Object.values(hit.hierarchy).filter(
+      (v): v is string => Boolean(v),
+    )
+    return {
+      title: hit.hierarchy.lvl1 || hit.hierarchy.lvl0 || 'Untitled',
+      url: hit.url,
+      snippet: hit._snippetResult?.content?.value || hit.content || '',
+      library: hit.library || 'unknown',
+      breadcrumb,
+    }
+  })
+
+  return {
+    query,
+    totalHits: searchResult.nbHits || results.length,
+    results,
+  }
+}

package/src/options.ts

@@ -4,6 +4,7 @@ import {
   finalizeAddOns,
   getFrameworkById,
   getPackageManager,
+  loadStarter,
   populateAddOnOptionsDefaults,
   readConfigFile,
 } from '@tanstack/create'
@@ -17,8 +18,13 @@ import {
   selectExamples,
   selectGit,
   selectPackageManager,
+  selectTemplate,
   selectToolchain,
 } from './ui-prompts.js'
+import {
+  listTemplateChoices,
+  resolveStarterSpecifier,
+} from './command-line.js'
 
 import {
   getCurrentDirectoryName,
@@ -72,6 +78,39 @@ export async function promptForCreateOptions(
     !!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
 
@@ -114,6 +153,9 @@ export async function promptForCreateOptions(
   }
 
   if (!routerOnly) {
+    for (const addOn of starter?.dependsOn || []) {
+      addOns.add(addOn)
+    }
     for (const addOn of forcedAddOns) {
       addOns.add(addOn)
     }
@@ -188,6 +230,10 @@ export async function promptForCreateOptions(
     options.install = false
   }
 
+  if (starter) {
+    options.starter = starter
+  }
+
   return options
 }
 

package/src/types.ts

@@ -10,8 +10,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/src/ui-prompts.ts

@@ -60,6 +60,38 @@ export async function selectPackageManager(): Promise<PackageManager> {
   return packageManager
 }
 
+export async function selectTemplate(
+  templates: Array<{ id: string; name: string; description?: string }>,
+): Promise<string | undefined> {
+  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
 

package/tests/command-line.test.ts

@@ -340,6 +340,87 @@ describe('normalizeOptions', () => {
     }
   })
 
+  it('prefers framework-matching template ids from registry', async () => {
+    __testRegisterFramework({
+      id: 'react',
+      name: 'React',
+      getAddOns: () => [],
+      supportedModes: {
+        'file-router': {
+          displayName: 'File Router',
+          description: 'TanStack Router using files to define the routes',
+          forceTypescript: true,
+        },
+      },
+    })
+    __testRegisterFramework({
+      id: 'solid',
+      name: 'Solid',
+      getAddOns: () => [],
+      supportedModes: {
+        'file-router': {
+          displayName: 'File Router',
+          description: 'TanStack Router using files to define the routes',
+          forceTypescript: true,
+        },
+      },
+    })
+
+    const originalRegistry = process.env.CTA_REGISTRY
+    process.env.CTA_REGISTRY = 'https://registry.example/registry.json'
+
+    fetch
+      .mockResponseOnce(
+        JSON.stringify({
+          templates: [
+            {
+              name: 'Blog',
+              description: 'React blog template',
+              url: './react/blog/template.json',
+              mode: 'file-router',
+              framework: 'react',
+            },
+            {
+              name: 'Blog',
+              description: 'Solid blog template',
+              url: './solid/blog/template.json',
+              mode: 'file-router',
+              framework: 'solid',
+            },
+          ],
+        }),
+      )
+      .mockResponseOnce(
+        JSON.stringify({
+          id: 'blog',
+          typescript: true,
+          framework: 'solid',
+          mode: 'file-router',
+          type: 'starter',
+          description: 'Solid blog template',
+          name: 'Blog',
+          dependsOn: [],
+          files: {},
+          deletedFiles: [],
+        }),
+      )
+
+    try {
+      const options = await normalizeOptions({
+        projectName: 'test',
+        framework: 'solid',
+        template: 'blog',
+      })
+
+      expect(options?.framework?.id).toBe('solid')
+      expect(options?.starter?.id).toBe(
+        'https://registry.example/solid/blog/template.json',
+      )
+    } finally {
+      process.env.CTA_REGISTRY = originalRegistry
+    }
+  })
+
   it('should default to react if no framework is provided', async () => {
     __testRegisterFramework({
       id: 'react',

package/tests/options.test.ts

@@ -5,14 +5,17 @@ import {
   __testClearFrameworks,
   __testRegisterFramework,
 } from '@tanstack/create'
+import * as create from '@tanstack/create'
 
 import * as prompts from '../src/ui-prompts'
+import * as commandLine from '../src/command-line'
 
 import type { Framework } from '@tanstack/create'
 
 import type { CliOptions } from '../src/types'
 
 vi.mock('../src/ui-prompts')
+vi.mock('../src/command-line')
 
 beforeEach(() => {
   __testClearFrameworks()
@@ -61,7 +64,31 @@ const baseCliOptions: CliOptions = {
 }
 
 function setBasicSpies() {
+  vi.spyOn(commandLine, 'listTemplateChoices').mockImplementation(async () => [])
+  vi
+    .spyOn(commandLine, 'resolveStarterSpecifier')
+    .mockImplementation(async (value) =>
+      value === 'blog'
+        ? 'https://example.com/react/blog/starter.json'
+        : value,
+    )
+  vi.spyOn(create, 'loadStarter').mockImplementation(
+    async (id) =>
+      ({
+        id: String(id),
+        name: 'Blog',
+        description: 'Blog template',
+        type: 'starter',
+        framework: 'react',
+        mode: 'file-router',
+        typescript: true,
+        dependsOn: [],
+        files: {},
+        deletedFiles: [],
+      }) as any,
+  )
   vi.spyOn(prompts, 'getProjectName').mockImplementation(async () => 'hello')
+  vi.spyOn(prompts, 'selectTemplate').mockImplementation(async () => undefined)
   vi.spyOn(prompts, 'selectPackageManager').mockImplementation(
     async () => 'npm',
   )
@@ -111,6 +138,44 @@ describe('promptForCreateOptions', () => {
     expect(options?.tailwind).toBe(true)
   })
 
+  it('prompts for templates when none was provided', async () => {
+    setBasicSpies()
+    vi.spyOn(commandLine, 'listTemplateChoices').mockImplementation(async () => [
+      {
+        id: 'blog',
+        name: 'Blog',
+        description: 'Blog template',
+        framework: 'react',
+      },
+    ])
+
+    await promptForCreateOptions(baseCliOptions, {})
+
+    expect(prompts.selectTemplate).toHaveBeenCalledWith([
+      {
+        id: 'blog',
+        name: 'Blog',
+        description: 'Blog template',
+      },
+    ])
+  })
+
+  it('skips template prompt when template was provided via CLI', async () => {
+    setBasicSpies()
+
+    await promptForCreateOptions({ ...baseCliOptions, template: 'blog' }, {})
+
+    expect(prompts.selectTemplate).not.toHaveBeenCalled()
+  })
+
+  it('skips template prompt in router-only mode', async () => {
+    setBasicSpies()
+
+    await promptForCreateOptions({ ...baseCliOptions, routerOnly: true }, {})
+
+    expect(prompts.selectTemplate).not.toHaveBeenCalled()
+  })
+
   //// Package manager
 
   it('uses the package manager from the cli options', async () => {

package/tests/ui-prompts.test.ts

@@ -7,6 +7,7 @@ import {
   selectAddOns,
   selectGit,
   selectPackageManager,
+  selectTemplate,
   selectToolchain,
 } from '../src/ui-prompts'
 
@@ -54,6 +55,33 @@ describe('selectPackageManager', () => {
   })
 })
 
+describe('selectTemplate', () => {
+  it('should select a template id', async () => {
+    vi.spyOn(clack, 'select').mockImplementation(async () => 'blog')
+    vi.spyOn(clack, 'isCancel').mockImplementation(() => false)
+
+    const selectedTemplate = await selectTemplate([
+      { id: 'blog', name: 'Blog', description: 'A blog template' },
+    ])
+
+    expect(selectedTemplate).toBe('blog')
+  })
+
+  it('should return undefined when no templates are available', async () => {
+    const selectedTemplate = await selectTemplate([])
+    expect(selectedTemplate).toBeUndefined()
+  })
+
+  it('should exit on cancel', async () => {
+    vi.spyOn(clack, 'select').mockImplementation(async () => Symbol.for('cancel'))
+    vi.spyOn(clack, 'isCancel').mockImplementation(() => true)
+
+    await expect(
+      selectTemplate([{ id: 'blog', name: 'Blog' }]),
+    ).rejects.toThrowError(/exit/)
+  })
+})
+
 describe('selectAddOns', () => {
   it('should show keyboard shortcuts help and select add-ons', async () => {
     const noteSpy = vi.spyOn(clack, 'note').mockImplementation(() => {})

package/tests-e2e/create-smoke.spec.ts

@@ -2,7 +2,7 @@ import { expect, test } from '@playwright/test'
 
 import { attachRuntimeGuards, createReactAppFixture } from './helpers'
 
-test('@blocking creates a React app and navigates core demo routes', async ({ page }) => {
+test('@blocking creates a React app and navigates core starter routes', async ({ page }) => {
   const fixture = await createReactAppFixture({
     appName: 'react-smoke-app',
   })
@@ -12,21 +12,21 @@ test('@blocking creates a React app and navigates core demo routes', async ({ pa
     await page.goto(fixture.url)
     await expect(
       page.getByRole('heading', {
-        name: 'Island hours, but for product teams.',
+        name: 'Start simple, ship quickly.',
       }),
     ).toBeVisible()
 
-    await page.getByRole('link', { name: 'Blog' }).click()
-    await expect(page).toHaveURL(/\/blog\/?$/)
-    await expect(page.getByRole('heading', { name: 'Blog' })).toBeVisible()
-
-    await page.locator('main article a').first().click()
-    await expect(page).toHaveURL(/\/blog\/.+/)
-    await expect(page.getByText('Post', { exact: true })).toBeVisible()
-
-    await page.getByRole('link', { name: 'About' }).click()
+    await page.getByRole('link', { name: 'About', exact: true }).click()
     await expect(page).toHaveURL(/\/about\/?$/)
-    await expect(page.getByRole('heading', { name: 'Built for shipping fast.' })).toBeVisible()
+    await expect(
+      page.getByRole('heading', { name: 'A small starter with room to grow.' }),
+    ).toBeVisible()
+
+    await page.getByRole('link', { name: 'Home' }).click()
+    await expect(page).toHaveURL(/\/?$/)
+    await expect(
+      page.getByRole('heading', { name: 'Start simple, ship quickly.' }),
+    ).toBeVisible()
   } finally {
     try {
       guards.assertClean()

package/tests-e2e/router-only-smoke.spec.ts

@@ -14,7 +14,7 @@ test('@blocking creates a React router-only app and navigates every internal lin
   try {
     await page.goto(fixture.url)
     await expect(
-      page.getByRole('heading', { name: 'Island hours, but for product teams.' }),
+      page.getByRole('heading', { name: 'Start simple, ship quickly.' }),
     ).toBeVisible()
 
     const homeLinks = await page
@@ -25,36 +25,22 @@ test('@blocking creates a React router-only app and navigates every internal lin
           .sort(),
       )
 
-    expect(homeLinks).toContain('/blog')
+    expect(homeLinks).toContain('/about')
 
-    await page.locator('a[href="/blog"]').first().click()
-    await expect(page).toHaveURL(/\/blog\/?$/)
-    await expect(page.getByRole('heading', { name: 'Blog' })).toBeVisible()
-
-    const blogPostLinks = await page
-      .locator('a[href^="/blog/"]')
-      .evaluateAll((anchors) =>
-        Array.from(new Set(anchors.map((anchor) => anchor.getAttribute('href') || '')))
-          .filter(Boolean)
-          .sort(),
-      )
-
-    expect(blogPostLinks.length).toBeGreaterThan(0)
-
-    for (const postPath of blogPostLinks) {
-      await page.locator(`a[href="${postPath}"]`).first().click()
-      await expect(page).toHaveURL(new RegExp(`${postPath}/?$`))
-      await expect(page.locator('h1').first()).toBeVisible()
-      await page.goBack()
-      await expect(page).toHaveURL(/\/blog\/?$/)
-    }
+    await page.locator('a[href="/about"]').first().click()
+    await expect(page).toHaveURL(/\/about\/?$/)
+    await expect(
+      page.getByRole('heading', { name: 'A small starter with room to grow.' }),
+    ).toBeVisible()
 
     await page.goto(`${fixture.url}/about`)
-    await expect(page.getByRole('heading', { name: 'Built for shipping fast.' })).toBeVisible()
+    await expect(
+      page.getByRole('heading', { name: 'A small starter with room to grow.' }),
+    ).toBeVisible()
 
     await page.goto(fixture.url)
     await expect(
-      page.getByRole('heading', { name: 'Island hours, but for product teams.' }),
+      page.getByRole('heading', { name: 'Start simple, ship quickly.' }),
     ).toBeVisible()
   } finally {
     try {

package/tests-e2e/solid-smoke.spec.ts

@@ -11,8 +11,9 @@ test('@blocking creates a Solid app and renders the home route', async ({ page }
 
   try {
     await page.goto(fixture.url)
-    await expect(page.getByRole('heading', { name: /TANSTACK/i })).toBeVisible()
-    await expect(page.getByText('The framework for next generation AI applications')).toBeVisible()
+    await expect(
+      page.getByRole('heading', { name: 'Start simple, ship quickly.' }),
+    ).toBeVisible()
   } finally {
     try {
       guards.assertClean()