@tanstack/create 0.49.1

package/src/registry.ts

@@ -0,0 +1,106 @@
+import { z } from 'zod'
+import { loadRemoteAddOn } from './custom-add-ons/add-on.js'
+import { loadStarter } from './custom-add-ons/starter.js'
+import { handleSpecialURL } from './utils.js'
+
+import type { AddOn, Starter } from './types'
+
+const registrySchema = z.object({
+  starters: z
+    .array(
+      z.object({
+        name: z.string(),
+        description: z.string(),
+        url: z.string(),
+        banner: z.string().optional(),
+        mode: z.string(),
+        framework: z.string(),
+      }),
+    )
+    .optional(),
+  'add-ons': z
+    .array(
+      z.object({
+        name: z.string(),
+        description: z.string(),
+        url: z.string(),
+        modes: z.array(z.string()),
+        framework: z.string(),
+      }),
+    )
+    .optional(),
+})
+
+export type Registry = z.infer<typeof registrySchema>
+
+function absolutizeUrl(originalUrl: string, relativeUrl: string) {
+  if (relativeUrl.startsWith('http') || relativeUrl.startsWith('https')) {
+    return relativeUrl
+  }
+  const baseUrl = originalUrl.replace(/registry.json$/, '')
+  return `${baseUrl}${relativeUrl.replace(/^\.\//, '')}`
+}
+
+export async function getRawRegistry(
+  registryUrl?: string,
+): Promise<Registry | undefined> {
+  const regUrl = registryUrl || process.env.CTA_REGISTRY
+  if (regUrl) {
+    const url = handleSpecialURL(regUrl)
+    const registry = (await fetch(url).then((res) => res.json())) as Registry
+    const parsedRegistry = registrySchema.parse(registry)
+    for (const addOn of parsedRegistry['add-ons'] || []) {
+      addOn.url = absolutizeUrl(url, addOn.url)
+    }
+    for (const starter of parsedRegistry.starters || []) {
+      starter.url = absolutizeUrl(url, starter.url)
+      if (starter.banner) {
+        starter.banner = absolutizeUrl(url, starter.banner)
+      }
+    }
+    return parsedRegistry
+  }
+}
+
+async function getAddOns(registry: Registry): Promise<Array<AddOn>> {
+  const addOns: Array<AddOn> = []
+  for (const addOnInfo of registry['add-ons'] || []) {
+    const addOn = await loadRemoteAddOn(addOnInfo.url)
+    addOns.push(addOn)
+  }
+  return addOns
+}
+
+export async function getRegistryAddOns(
+  registryUrl?: string,
+): Promise<Array<AddOn>> {
+  const registry = await getRawRegistry(registryUrl)
+  return registry ? await getAddOns(registry) : []
+}
+
+async function getStarters(registry: Registry): Promise<Array<Starter>> {
+  const starters: Array<Starter> = []
+  for (const starterInfo of registry.starters || []) {
+    const starter = await loadStarter(starterInfo.url)
+    starters.push(starter)
+  }
+  return starters
+}
+
+export async function getRegistryStarters(
+  registryUrl?: string,
+): Promise<Array<Starter>> {
+  const registry = await getRawRegistry(registryUrl)
+  return registry ? await getStarters(registry) : []
+}
+
+export async function getRegistry(registryUrl?: string): Promise<{
+  addOns: Array<AddOn>
+  starters: Array<Starter>
+}> {
+  const registry = await getRawRegistry(registryUrl)
+  return {
+    addOns: registry ? await getAddOns(registry) : [],
+    starters: registry ? await getStarters(registry) : [],
+  }
+}

package/src/special-steps/index.ts

@@ -0,0 +1,38 @@
+import { rimrafNodeModules } from './rimraf-node-modules.js'
+import { postInitScript } from './post-init-script.js'
+
+import type { Environment, Options } from '../types.js'
+
+const specialStepsLookup: Record<
+  string,
+  (environment: Environment, options: Options) => Promise<void>
+> = {
+  'rimraf-node-modules': rimrafNodeModules,
+  'post-init-script': postInitScript,
+}
+
+export async function runSpecialSteps(
+  environment: Environment,
+  options: Options,
+  specialSteps: Array<string>,
+) {
+  if (specialSteps.length) {
+    environment.startStep({
+      id: 'special-steps',
+      type: 'command',
+      message: 'Running special steps...',
+    })
+
+    for (const step of specialSteps) {
+      const stepFunction = specialStepsLookup[step]
+      /* eslint-disable @typescript-eslint/no-unnecessary-condition */
+      if (stepFunction) {
+        await stepFunction(environment, options)
+      } else {
+        environment.error(`Special step ${step} not found`)
+      }
+    }
+
+    environment.finishStep('special-steps', 'Special steps complete')
+  }
+}

package/src/special-steps/post-init-script.ts

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { getPackageManagerScriptCommand } from '../package-manager.js'
+
+import type { Environment, Options } from '../types.js'
+
+export async function postInitScript(
+  environment: Environment,
+  options: Options,
+) {
+  const packageJsonPath = resolve(options.targetDir, 'package.json')
+
+  if (!environment.exists(packageJsonPath)) {
+    environment.warn(
+      'Warning',
+      'No package.json found, skipping post-cta-init script',
+    )
+    return
+  }
+
+  try {
+    const packageJsonContent = readFileSync(packageJsonPath, 'utf-8')
+    const packageJson = JSON.parse(packageJsonContent)
+
+    if (!packageJson.scripts || !packageJson.scripts['post-cta-init']) {
+      // No post-cta-init script found, skip silently
+      return
+    }
+
+    environment.startStep({
+      id: 'post-init-script',
+      type: 'command',
+      message: 'Running post-cta-init script...',
+    })
+
+    const { command, args } = getPackageManagerScriptCommand(
+      options.packageManager,
+      ['post-cta-init'],
+    )
+
+    await environment.execute(command, args, options.targetDir, {
+      inherit: true,
+    })
+
+    environment.finishStep('post-init-script', 'Post-cta-init script complete')
+  } catch (error) {
+    environment.error(
+      `Failed to run post-cta-init script: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+}

package/src/special-steps/rimraf-node-modules.ts

@@ -0,0 +1,25 @@
+import { resolve } from 'node:path'
+
+import type { Environment, Options } from '../types.js'
+
+const lockFiles = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml']
+
+export async function rimrafNodeModules(
+  environment: Environment,
+  options: Options,
+) {
+  environment.startStep({
+    id: 'special-steps',
+    type: 'command',
+    message: 'Removing node_modules...',
+  })
+
+  await environment.rimraf(resolve(options.targetDir, 'node_modules'))
+
+  for (const lockFile of lockFiles) {
+    const lockFilePath = resolve(options.targetDir, lockFile)
+    if (environment.exists(lockFilePath)) {
+      await environment.deleteFile(lockFilePath)
+    }
+  }
+}

package/src/template-file.ts

@@ -0,0 +1,182 @@
+import { resolve, sep } from 'node:path'
+import { render } from 'ejs'
+import { format } from 'prettier'
+
+import { formatCommand } from './utils.js'
+import {
+  getPackageManagerInstallCommand,
+  getPackageManagerScriptCommand,
+} from './package-manager.js'
+import { relativePath } from './file-helpers.js'
+
+import type {
+  AddOn,
+  Environment,
+  Integration,
+  IntegrationWithSource,
+  Options,
+} from './types.js'
+
+function convertDotFilesAndPaths(path: string) {
+  return path
+    .split(sep)
+    .map((segment) => segment.replace(/^_dot_/, '.'))
+    .join(sep)
+}
+
+export function createTemplateFile(environment: Environment, options: Options) {
+  function getPackageManagerAddScript(
+    packageName: string,
+    isDev: boolean = false,
+  ) {
+    return formatCommand(
+      getPackageManagerInstallCommand(
+        options.packageManager,
+        packageName,
+        isDev,
+      ),
+    )
+  }
+  function getPackageManagerRunScript(
+    scriptName: string,
+    args: Array<string> = [],
+  ) {
+    return formatCommand(
+      getPackageManagerScriptCommand(options.packageManager, [
+        scriptName,
+        ...args,
+      ]),
+    )
+  }
+
+  class IgnoreFileError extends Error {
+    constructor() {
+      super('ignoreFile')
+      this.name = 'IgnoreFileError'
+    }
+  }
+
+  // Collect integrations and tag them with source add-on for attribution
+  const integrations: Array<IntegrationWithSource> = []
+  for (const addOn of options.chosenAddOns) {
+    if (addOn.integrations) {
+      for (const integration of addOn.integrations) {
+        integrations.push({
+          ...integration,
+          _sourceId: addOn.id,
+          _sourceName: addOn.name,
+        })
+      }
+    }
+  }
+
+  const routes: Array<Required<AddOn>['routes'][number]> = []
+  for (const addOn of options.chosenAddOns) {
+    if (addOn.routes) {
+      routes.push(...addOn.routes)
+    }
+  }
+
+  const addOnEnabled = options.chosenAddOns.reduce<Record<string, boolean>>(
+    (acc, addOn) => {
+      acc[addOn.id] = true
+      return acc
+    },
+    {},
+  )
+
+  return async function templateFile(file: string, content: string) {
+    const localRelativePath = (path: string, stripExtension: boolean = false) =>
+      relativePath(file, path, stripExtension)
+
+    const integrationImportContent = (integration: Integration) =>
+      integration.import ||
+      `import ${integration.jsName} from '${localRelativePath(integration.path || '')}'`
+
+    const integrationImportCode = (integration: Integration) =>
+      integration.code || integration.jsName
+
+    const templateValues = {
+      packageManager: options.packageManager,
+      projectName: options.projectName,
+      typescript: options.typescript,
+      tailwind: options.tailwind,
+      js: options.typescript ? 'ts' : 'js',
+      jsx: options.typescript ? 'tsx' : 'jsx',
+      fileRouter: options.mode === 'file-router',
+      codeRouter: options.mode === 'code-router',
+      addOnEnabled,
+      addOnOption: options.addOnOptions,
+      addOns: options.chosenAddOns,
+      integrations,
+      routes,
+
+      getPackageManagerAddScript,
+      getPackageManagerRunScript,
+
+      relativePath: (path: string, stripExtension: boolean = false) =>
+        relativePath(file, path, stripExtension),
+
+      integrationImportContent,
+      integrationImportCode,
+
+      ignoreFile: () => {
+        throw new IgnoreFileError()
+      },
+    }
+
+    let ignoreFile = false
+
+    if (file.endsWith('.ejs')) {
+      try {
+        content = render(content, templateValues)
+      } catch (error) {
+        if (error instanceof IgnoreFileError) {
+          ignoreFile = true
+        } else {
+          console.error(file, error)
+          environment.error(`EJS error in file ${file}`, error?.toString())
+          process.exit(1)
+        }
+      }
+    }
+
+    if (ignoreFile) {
+      return
+    }
+
+    let target = convertDotFilesAndPaths(file.replace('.ejs', ''))
+
+    // Strip option prefixes from filename (e.g., __postgres__schema.prisma -> schema.prisma)
+    const prefixMatch = target.match(/^(.+\/)?__([^_]+)__(.+)$/)
+    if (prefixMatch) {
+      const [, directory, , filename] = prefixMatch
+      target = (directory || '') + filename
+    }
+
+    let append = false
+    if (target.endsWith('.append')) {
+      append = true
+      target = target.replace('.append', '')
+    }
+
+    if (target.endsWith('.ts') || target.endsWith('.tsx')) {
+      content = await format(content, {
+        semi: false,
+        singleQuote: true,
+        trailingComma: 'all',
+        parser: 'typescript',
+      })
+    }
+
+    if (!options.typescript) {
+      target = target.replace(/\.tsx$/, '.jsx').replace(/\.ts$/, '.js')
+    }
+
+    if (append) {
+      await environment.appendFile(resolve(options.targetDir, target), content)
+    } else {
+      await environment.writeFile(resolve(options.targetDir, target), content)
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,312 @@
+import z from 'zod'
+
+import type { PackageManager } from './package-manager.js'
+
+export type StatusStepType =
+  | 'file'
+  | 'command'
+  | 'info'
+  | 'package-manager'
+  | 'other'
+
+export const AddOnSelectOptionSchema = z.object({
+  type: z.literal('select'),
+  label: z.string(),
+  description: z.string().optional(),
+  default: z.string(),
+  options: z.array(
+    z.object({
+      value: z.string(),
+      label: z.string(),
+    }),
+  ),
+})
+
+export const AddOnOptionSchema = z.discriminatedUnion('type', [
+  AddOnSelectOptionSchema,
+])
+
+export const AddOnOptionsSchema = z.record(z.string(), AddOnOptionSchema)
+
+export const AddOnBaseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  author: z.string().optional(),
+  version: z.string().optional(),
+  link: z.string().optional(),
+  license: z.string().optional(),
+  warning: z.string().optional(),
+  tailwind: z.boolean().optional().default(true),
+  type: z.enum(['add-on', 'example', 'starter', 'toolchain', 'deployment']),
+  category: z
+    .enum([
+      'tanstack',
+      'database',
+      'orm',
+      'auth',
+      'deploy',
+      'styling',
+      'monitoring',
+      'cms',
+      'api',
+      'i18n',
+      'tooling',
+      'other',
+    ])
+    .optional(),
+  exclusive: z
+    .array(z.enum(['orm', 'auth', 'deploy', 'database', 'linter']))
+    .optional(),
+  color: z.string().optional(),
+  priority: z.number().optional(),
+  command: z
+    .object({
+      command: z.string(),
+      args: z.array(z.string()).optional(),
+    })
+    .optional(),
+  routes: z
+    .array(
+      z.object({
+        url: z.string().optional(),
+        name: z.string().optional(),
+        path: z.string(),
+        jsName: z.string(),
+      }),
+    )
+    .optional(),
+  packageAdditions: z
+    .object({
+      dependencies: z.record(z.string(), z.string()).optional(),
+      devDependencies: z.record(z.string(), z.string()).optional(),
+      scripts: z.record(z.string(), z.string()).optional(),
+    })
+    .optional(),
+  shadcnComponents: z.array(z.string()).optional(),
+  dependsOn: z.array(z.string()).optional(),
+  smallLogo: z.string().optional(),
+  logo: z.string().optional(),
+  addOnSpecialSteps: z.array(z.string()).optional(),
+  createSpecialSteps: z.array(z.string()).optional(),
+  postInitSpecialSteps: z.array(z.string()).optional(),
+  options: AddOnOptionsSchema.optional(),
+  default: z.boolean().optional(),
+})
+
+export const StarterSchema = AddOnBaseSchema.extend({
+  framework: z.string(),
+  mode: z.string(),
+  typescript: z.boolean(),
+  tailwind: z.boolean(),
+  banner: z.string().optional(),
+})
+
+export const StarterCompiledSchema = StarterSchema.extend({
+  files: z.record(z.string(), z.string()),
+  deletedFiles: z.array(z.string()),
+})
+
+export const IntegrationSchema = z.object({
+  type: z.string().optional(),
+  path: z.string().optional(),
+  jsName: z.string().optional(),
+  import: z.string().optional(),
+  code: z.string().optional(),
+})
+
+export const AddOnInfoSchema = AddOnBaseSchema.extend({
+  modes: z.array(z.string()),
+  integrations: z.array(IntegrationSchema).optional(),
+  phase: z.enum(['setup', 'add-on']),
+  readme: z.string().optional(),
+})
+
+export const AddOnCompiledSchema = AddOnInfoSchema.extend({
+  files: z.record(z.string(), z.string()),
+  deletedFiles: z.array(z.string()),
+  packageTemplate: z.string().optional(),
+})
+
+export type AddOnSelectOption = z.infer<typeof AddOnSelectOptionSchema>
+
+export type AddOnOption = z.infer<typeof AddOnOptionSchema>
+
+export type AddOnOptions = z.infer<typeof AddOnOptionsSchema>
+
+export type Integration = z.infer<typeof IntegrationSchema>
+
+export type AddOnBase = z.infer<typeof AddOnBaseSchema>
+
+export type StarterInfo = z.infer<typeof StarterSchema>
+
+export type StarterCompiled = z.infer<typeof StarterCompiledSchema>
+
+export type AddOnInfo = z.infer<typeof AddOnInfoSchema>
+
+export type AddOnCompiled = z.infer<typeof AddOnCompiledSchema>
+
+export interface AddOnSelection {
+  id: string
+  enabled: boolean
+  options: Record<string, any>
+}
+
+export type FileBundleHandler = {
+  getFiles: () => Promise<Array<string>>
+  getFileContents: (path: string) => Promise<string>
+  getDeletedFiles: () => Promise<Array<string>>
+}
+
+export type AddOn = AddOnCompiled & FileBundleHandler
+
+export type Starter = StarterCompiled & FileBundleHandler
+
+export type FrameworkDefinition = {
+  id: string
+  name: string
+  description: string
+  version: string
+
+  base: Record<string, string>
+  addOns: Array<AddOn>
+  basePackageJSON: Record<string, any>
+  optionalPackages: Record<string, any>
+
+  supportedModes: Record<
+    string,
+    {
+      displayName: string
+      description: string
+      forceTypescript: boolean
+    }
+  >
+}
+
+export type Framework = Omit<FrameworkDefinition, 'base' | 'addOns'> &
+  FileBundleHandler & {
+    getAddOns: () => Array<AddOn>
+  }
+
+export interface Options {
+  projectName: string
+  targetDir: string
+
+  framework: Framework
+  mode: string
+
+  typescript: boolean
+  tailwind: boolean
+
+  packageManager: PackageManager
+  git: boolean
+  install?: boolean
+
+  chosenAddOns: Array<AddOn>
+  addOnOptions: Record<string, Record<string, any>>
+  starter?: Starter | undefined
+}
+
+export type SerializedOptions = Omit<
+  Options,
+  'chosenAddOns' | 'starter' | 'framework'
+> & {
+  chosenAddOns: Array<string>
+  starter?: string | undefined
+  framework: string
+}
+
+type ProjectEnvironment = {
+  startRun: () => void
+  finishRun: () => void
+  getErrors: () => Array<string>
+}
+
+type FileEnvironment = {
+  appendFile: (path: string, contents: string) => Promise<void>
+  copyFile: (from: string, to: string) => Promise<void>
+  writeFile: (path: string, contents: string) => Promise<void>
+  writeFileBase64: (path: string, base64Contents: string) => Promise<void>
+  execute: (
+    command: string,
+    args: Array<string>,
+    cwd: string,
+    options?: { inherit?: boolean },
+  ) => Promise<{ stdout: string }>
+  deleteFile: (path: string) => Promise<void>
+
+  exists: (path: string) => boolean
+  isDirectory: (path: string) => boolean
+  readFile: (path: string) => Promise<string>
+  readdir: (path: string) => Promise<Array<string>>
+  rimraf: (path: string) => Promise<void>
+}
+
+export type StatusEvent = {
+  id: string
+  type: StatusStepType
+  message: string
+}
+export type StopEvent = {
+  id: string
+}
+
+type UIEnvironment = {
+  appName: string
+
+  startStep: (info: {
+    id: string
+    type: StatusStepType
+    message: string
+  }) => void
+  finishStep: (id: string, finalMessage: string) => void
+
+  intro: (message: string) => void
+  outro: (message: string) => void
+
+  info: (title?: string, message?: string) => void
+  error: (title?: string, message?: string) => void
+  warn: (title?: string, message?: string) => void
+
+  spinner: () => {
+    start: (message: string) => void
+    stop: (message: string) => void
+  }
+  confirm: (message: string) => Promise<boolean>
+}
+
+export type Environment = ProjectEnvironment & FileEnvironment & UIEnvironment
+
+// Attribution tracking types for file provenance
+export interface LineAttribution {
+  line: number
+  sourceId: string
+  sourceName: string
+  type: 'original' | 'injected'
+}
+
+export interface FileProvenance {
+  source: 'framework' | 'add-on' | 'starter'
+  sourceId: string
+  sourceName: string
+}
+
+export interface AttributedFile {
+  content: string
+  provenance: FileProvenance
+  lineAttributions: Array<LineAttribution>
+}
+
+export interface DependencyAttribution {
+  name: string
+  version: string
+  type: 'dependency' | 'devDependency'
+  sourceId: string
+  sourceName: string
+}
+
+// Integration with source add-on tracking (used in templates and attribution)
+export type IntegrationWithSource = Integration & {
+  _sourceId: string
+  _sourceName: string
+}