@tanstack/create 0.49.1

package/dist/types/utils.d.ts

@@ -0,0 +1,7 @@
+export declare function sortObject(obj: Record<string, string>): Record<string, string>;
+export declare function jsSafeName(name: string): string;
+export declare function formatCommand({ command, args, }: {
+    command: string;
+    args: Array<string>;
+}): string;
+export declare function handleSpecialURL(url: string): string;

package/dist/types.js

@@ -0,0 +1,107 @@
+import z from 'zod';
+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(),
+});

package/dist/utils.js

@@ -0,0 +1,31 @@
+export function sortObject(obj) {
+    return Object.keys(obj)
+        .sort()
+        .reduce((acc, key) => {
+        acc[key] = obj[key];
+        return acc;
+    }, {});
+}
+export function jsSafeName(name) {
+    return name
+        .split(/[^a-zA-Z0-9]/)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+export function formatCommand({ command, args, }) {
+    return `${command} ${args.join(' ')}`.trim();
+}
+// Turn GitHub URLs into raw URLs
+export function handleSpecialURL(url) {
+    if (url.startsWith('https://github.com/') && url.includes('blob')) {
+        return url
+            .replace('https://github.com/', 'https://raw.githubusercontent.com/')
+            .replace('/blob/', '/refs/heads/');
+    }
+    if (url.startsWith('https://github.com/') && url.includes('tree')) {
+        return url
+            .replace('https://github.com/', 'https://raw.githubusercontent.com/')
+            .replace('/tree/', '/refs/heads/');
+    }
+    return url;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@tanstack/create",
+  "version": "0.49.1",
+  "description": "TanStack Application Builder Engine",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "scripts": {
+    "build": "tsc && npm run copy-assets",
+    "copy-assets": "node -e \"const fs=require('fs');const path=require('path');function copyDir(src,dest){if(!fs.existsSync(dest))fs.mkdirSync(dest,{recursive:true});for(const entry of fs.readdirSync(src,{withFileTypes:true})){const srcPath=path.join(src,entry.name);const destPath=path.join(dest,entry.name);if(entry.isDirectory())copyDir(srcPath,destPath);else if(!entry.name.endsWith('.ts')||entry.name.endsWith('.d.ts'))fs.copyFileSync(srcPath,destPath)}}['react','solid'].forEach(fw=>{['add-ons','toolchains','hosts','examples','project'].forEach(dir=>{const src='src/frameworks/'+fw+'/'+dir;const dest='dist/frameworks/'+fw+'/'+dir;if(fs.existsSync(src))copyDir(src,dest)})})\"",
+    "dev": "tsc --watch",
+    "test": "eslint ./src && vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/create-tsrouter-app.git",
+    "directory": "packages/create"
+  },
+  "homepage": "https://tanstack.com/router",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "tanstack",
+    "router",
+    "create-tsrouter-app"
+  ],
+  "author": "Jack Herrington <jherr@pobox.com>",
+  "license": "MIT",
+  "packageManager": "pnpm@9.15.5",
+  "dependencies": {
+    "ejs": "^3.1.10",
+    "execa": "^9.5.2",
+    "ignore": "^7.0.3",
+    "memfs": "^4.17.0",
+    "parse-gitignore": "^2.0.0",
+    "prettier": "^3.5.0",
+    "rimraf": "^6.0.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/ejs": "^3.1.5",
+    "@types/node": "^22.13.4",
+    "@types/parse-gitignore": "^1.0.2",
+    "@vitest/coverage-v8": "3.1.1",
+    "eslint": "^9.20.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.0.8",
+    "vitest-fetch-mock": "^0.4.5"
+  }
+}

package/src/add-ons.ts

@@ -0,0 +1,74 @@
+import { loadRemoteAddOn } from './custom-add-ons/add-on.js'
+
+import type { AddOn, Framework } from './types.js'
+
+export function getAllAddOns(framework: Framework, mode: string): Array<AddOn> {
+  return framework
+    .getAddOns()
+    .filter((a) => a.modes.includes(mode))
+    .sort((a, b) => {
+      const aPriority = a.priority ?? 0
+      const bPriority = b.priority ?? 0
+      return bPriority - aPriority // Higher priority first
+    })
+}
+
+// Turn the list of chosen add-on IDs into a final list of add-ons by resolving dependencies
+export async function finalizeAddOns(
+  framework: Framework,
+  mode: string,
+  chosenAddOnIDs: Array<string>,
+): Promise<Array<AddOn>> {
+  const finalAddOnIDs = new Set(chosenAddOnIDs)
+
+  const addOns = getAllAddOns(framework, mode)
+
+  for (const addOnID of finalAddOnIDs) {
+    let addOn: AddOn | undefined
+    const localAddOn = addOns.find((a) => a.id === addOnID)
+    if (localAddOn) {
+      addOn = loadAddOn(localAddOn)
+    } else if (addOnID.startsWith('http')) {
+      addOn = await loadRemoteAddOn(addOnID)
+      addOns.push(addOn)
+    } else {
+      throw new Error(`Add-on ${addOnID} not found`)
+    }
+
+    for (const dependsOn of addOn.dependsOn || []) {
+      const dep = addOns.find((a) => a.id === dependsOn)
+      if (!dep) {
+        throw new Error(`Dependency ${dependsOn} not found`)
+      }
+      finalAddOnIDs.add(dep.id)
+    }
+  }
+
+  const finalAddOns = [...finalAddOnIDs].map(
+    (id) => addOns.find((a) => a.id === id)!,
+  )
+
+  return finalAddOns
+}
+
+function loadAddOn(addOn: AddOn): AddOn {
+  return addOn
+}
+
+export function populateAddOnOptionsDefaults(
+  chosenAddOns: Array<AddOn>,
+): Record<string, Record<string, any>> {
+  const addOnOptions: Record<string, Record<string, any>> = {}
+
+  for (const addOn of chosenAddOns) {
+    if (addOn.options) {
+      const defaults: Record<string, any> = {}
+      for (const [optionKey, optionDef] of Object.entries(addOn.options)) {
+        defaults[optionKey] = optionDef.default
+      }
+      addOnOptions[addOn.id] = defaults
+    }
+  }
+
+  return addOnOptions
+}

package/src/add-to-app.ts

@@ -0,0 +1,295 @@
+import { basename, resolve } from 'node:path'
+
+import { CONFIG_FILE } from './constants.js'
+import { finalizeAddOns } from './add-ons.js'
+import { getFrameworkById } from './frameworks.js'
+import { createMemoryEnvironment } from './environment.js'
+import { createApp } from './create-app.js'
+import {
+  readConfigFileFromEnvironment,
+  writeConfigFileToEnvironment,
+} from './config-file.js'
+import { formatCommand } from './utils.js'
+import { packageManagerInstall } from './package-manager.js'
+import {
+  isBase64,
+  recursivelyGatherFilesFromEnvironment,
+} from './file-helpers.js'
+import { mergePackageJSON } from './package-json.js'
+import { runSpecialSteps } from './special-steps/index.js'
+import { loadStarter } from './custom-add-ons/starter.js'
+
+import type { Environment, Options } from './types.js'
+import type { PersistedOptions } from './config-file.js'
+
+export async function hasPendingGitChanges(
+  environment: Environment,
+  cwd: string,
+) {
+  const { stdout } = await environment.execute(
+    'git',
+    ['status', '--porcelain'],
+    cwd,
+  )
+  return stdout.length > 0
+}
+
+async function createOptions(
+  json: PersistedOptions,
+  addOns: Array<string>,
+  targetDir: string,
+): Promise<Options> {
+  const framework = getFrameworkById(json.framework)
+
+  const starter = json.starter ? await loadStarter(json.starter) : undefined
+
+  return {
+    ...json,
+    framework,
+    tailwind: true,
+    addOns: true,
+    chosenAddOns: await finalizeAddOns(framework!, json.mode!, [
+      ...json.chosenAddOns,
+      ...addOns,
+    ]),
+    targetDir,
+    starter,
+  } as Options
+}
+
+async function runCreateApp(options: Required<Options>) {
+  const { environment, output } = createMemoryEnvironment(options.targetDir)
+  await createApp(environment, options)
+  return output
+}
+
+export async function getCurrentConfiguration(
+  environment: Environment,
+  cwd: string,
+) {
+  const persistedOptions = await readConfigFileFromEnvironment(environment, cwd)
+  if (!persistedOptions) {
+    environment.error(
+      'There is no .cta.json file in your project.',
+      'This is probably because this was created with an older version of create-tsrouter-app.',
+    )
+    return undefined
+  }
+
+  return persistedOptions
+}
+
+export async function writeFiles(
+  environment: Environment,
+  cwd: string,
+  output: {
+    files: Record<string, string>
+    deletedFiles: Array<string>
+  },
+  forced: boolean,
+) {
+  const currentFiles = await recursivelyGatherFilesFromEnvironment(
+    environment,
+    cwd,
+    false,
+  )
+
+  const overwrittenFiles: Array<string> = []
+  const changedFiles: Array<string> = []
+  for (const file of Object.keys(output.files)) {
+    const relativeFile = file.replace(cwd, '')
+    if (currentFiles[relativeFile]) {
+      if (currentFiles[relativeFile] !== output.files[file]) {
+        overwrittenFiles.push(relativeFile)
+      }
+    } else {
+      changedFiles.push(relativeFile)
+    }
+  }
+
+  if (!forced && overwrittenFiles.length) {
+    environment.warn(
+      'The following will be overwritten',
+      [...overwrittenFiles, ...output.deletedFiles].join('\n'),
+    )
+    const shouldContinue = await environment.confirm('Do you want to continue?')
+    if (!shouldContinue) {
+      throw new Error('User cancelled')
+    }
+  }
+
+  for (const file of output.deletedFiles) {
+    if (environment.exists(resolve(cwd, file))) {
+      await environment.deleteFile(resolve(cwd, file))
+    }
+  }
+
+  environment.startStep({
+    id: 'write-files',
+    type: 'file',
+    message: 'Writing add-on files...',
+  })
+
+  for (const file of [...changedFiles, ...overwrittenFiles]) {
+    const fName = basename(file)
+    const contents = output.files[file]
+    if (fName === 'package.json') {
+      const currentJson = JSON.parse(
+        await environment.readFile(resolve(cwd, file)),
+      )
+      const newJSON = mergePackageJSON(currentJson, JSON.parse(contents))
+      environment.writeFile(
+        resolve(cwd, file),
+        JSON.stringify(newJSON, null, 2),
+      )
+    } else if (fName !== CONFIG_FILE) {
+      if (isBase64(contents)) {
+        await environment.writeFileBase64(resolve(cwd, file), contents)
+      } else {
+        await environment.writeFile(resolve(cwd, file), contents)
+      }
+    }
+  }
+
+  environment.finishStep('write-files', 'Add-on files written')
+}
+
+export async function runNewCommands(
+  environment: Environment,
+  originalOptions: PersistedOptions,
+  cwd: string,
+  output: {
+    commands: Array<{
+      command: string
+      args: Array<string>
+    }>
+  },
+) {
+  const originalOutput = await runCreateApp({
+    ...(await createOptions(originalOptions, [], cwd)),
+  } as Required<Options>)
+
+  const originalCommands = new Set(
+    originalOutput.commands.map((c) => [c.command, ...c.args].join(' ')),
+  )
+
+  for (const command of output.commands) {
+    const commandString = [command.command, ...command.args].join(' ')
+    if (!originalCommands.has(commandString)) {
+      environment.startStep({
+        id: 'run-commands',
+        type: 'command',
+        message: `Running ${formatCommand({ command: command.command, args: command.args })}...`,
+      })
+      await environment.execute(command.command, command.args, cwd, {
+        inherit: true,
+      })
+      environment.finishStep('run-commands', 'Setup commands complete')
+    }
+  }
+}
+
+export async function addToApp(
+  environment: Environment,
+  addOns: Array<string>,
+  cwd: string,
+  options?: {
+    forced?: boolean
+  },
+) {
+  const persistedOptions = await getCurrentConfiguration(environment, cwd)
+  if (!persistedOptions) {
+    return
+  }
+
+  if (!options?.forced && (await hasPendingGitChanges(environment, cwd))) {
+    environment.error(
+      'You have pending git changes.',
+      'Please commit or stash them before adding add-ons.',
+    )
+    return
+  }
+
+  environment.intro(`Adding ${addOns.join(', ')} to the project...`)
+  environment.startStep({
+    id: 'processing-new-app-setup',
+    type: 'file',
+    message: 'Processing new app setup...',
+  })
+
+  const newOptions = await createOptions(persistedOptions, addOns, cwd)
+
+  const output = await runCreateApp({
+    ...newOptions,
+    targetDir: cwd,
+  } as Required<Options>)
+
+  await writeFiles(environment, cwd, output, !!options?.forced)
+
+  environment.finishStep(
+    'processing-new-app-setup',
+    'Application files written',
+  )
+
+  // Run any special steps for the new add-ons
+
+  const specialSteps = new Set<string>([])
+  for (const addOn of newOptions.chosenAddOns) {
+    for (const step of addOn.addOnSpecialSteps || []) {
+      if (addOns.includes(addOn.id)) {
+        specialSteps.add(step)
+      }
+    }
+  }
+  if (specialSteps.size) {
+    await runSpecialSteps(environment, newOptions, Array.from(specialSteps))
+  }
+
+  // Install dependencies
+
+  environment.startStep({
+    id: 'install-dependencies',
+    type: 'package-manager',
+    message: `Installing dependencies via ${newOptions.packageManager}...`,
+  })
+  const s = environment.spinner()
+  s.start(`Installing dependencies via ${newOptions.packageManager}...`)
+  await packageManagerInstall(
+    environment,
+    newOptions.targetDir,
+    newOptions.packageManager,
+  )
+  s.stop(`Installed dependencies`)
+  environment.finishStep('install-dependencies', 'Dependencies installed')
+
+  // Run any post-init special steps for the new add-ons
+  const postInitSpecialSteps = new Set<string>([])
+  for (const addOn of newOptions.chosenAddOns) {
+    for (const step of addOn.postInitSpecialSteps || []) {
+      if (addOns.includes(addOn.id)) {
+        postInitSpecialSteps.add(step)
+      }
+    }
+  }
+  if (postInitSpecialSteps.size) {
+    await runSpecialSteps(
+      environment,
+      newOptions,
+      Array.from(postInitSpecialSteps),
+    )
+  }
+
+  // Handle new commands
+
+  await runNewCommands(environment, persistedOptions, cwd, output)
+
+  environment.startStep({
+    id: 'write-config-file',
+    type: 'file',
+    message: 'Writing config file...',
+  })
+  writeConfigFileToEnvironment(environment, newOptions)
+  environment.finishStep('write-config-file', 'Config file written')
+
+  environment.outro(`Add-ons ${addOns.join(', ')} added!`)
+}