Skip to content
Source
Sign inSign up
TanStack/cli
Open History to see the last commit

create-app.ts

535 lines16.8 KB

1import { basename, resolve } from 'node:path'
2​
3import { isBase64, isDemoFilePath } from './file-helpers.js'
4import { formatCommand } from './utils.js'
5import { writeConfigFileToEnvironment } from './config-file.js'
6import {
7 detectPnpmVersion,
8 getPackageManagerInstallCommand,
9 getPackageManagerScriptCommand,
10 intentCommand,
11 packageManagerInstall,
12 translateExecuteCommand,
13 validatePackageManagerSupport,
14} from './package-manager.js'
15import { createPackageJSON } from './package-json.js'
16import { writePnpmWorkspace } from './pnpm-workspace.js'
17import { resolvePackageJSONLatest } from './npm-resolver.js'
18import { createTemplateFile } from './template-file.js'
19import { installShadcnComponents } from './integrations/shadcn.js'
20import { setupGit } from './integrations/git.js'
21import { setupIntent } from './integrations/intent.js'
22import { runSpecialSteps } from './special-steps/index.js'
23import { normalizeAndValidateBundlerOptions } from './build-tools.js'
24​
25import type { Environment, FileBundleHandler, Options } from './types.js'
26​
27function stripExamplesFromOptions(options: Options): Options {
28 const includeExamples =
29 options.projectPreset !== 'blank' && options.includeExamples !== false
30​
31 if (includeExamples) {
32 return options
33 }
34​
35 const chosenAddOns = options.chosenAddOns
36 .filter((addOn) => addOn.type !== 'example')
37 .map((addOn) => {
38 const filteredRoutes = (addOn.routes || []).filter(
39 (route) =>
40 !isDemoFilePath(route.path) &&
41 !(route.url && route.url.startsWith('/demo')),
42 )
43​
44 const filteredIntegrations = (addOn.integrations || []).filter(
45 (integration) => !isDemoFilePath(integration.path)
46 )
47​
48 return {
49 ...addOn,
50 routes: filteredRoutes,
51 integrations: filteredIntegrations,
52 getFiles: async () => {
53 const files = await addOn.getFiles()
54 return files.filter((file) => !isDemoFilePath(file))
55 },
56 getDeletedFiles: async () => {
57 const deletedFiles = await addOn.getDeletedFiles()
58 return deletedFiles.filter((file) => !isDemoFilePath(file))
59 },
60 }
61 })
62​
63 return {
64 ...options,
65 includeExamples: false,
66 chosenAddOns,
67 }
69​
70async function writeFiles(
71 environment: Environment,
72 options: Options,
73 context: { existingProject?: boolean } = {},
74) {
75 const workspaceWasPresent = environment.exists(
76 resolve(options.targetDir, 'pnpm-workspace.yaml'),
77 )
78 const templateFileFromContent = createTemplateFile(environment, options)
79​
80 async function writeFileBundle(bundle: FileBundleHandler) {
81 const files = await bundle.getFiles()
82​
83 for (const file of files) {
84 const contents = await bundle.getFileContents(file)
85​
86 const isBinaryFile = isBase64(contents)
87 if (isBinaryFile) {
88 await environment.writeFileBase64(
89 resolve(options.targetDir, file),
90 contents,
91 )
92 } else {
93 await templateFileFromContent(file, contents)
94 }
95 }
96​
97 const deletedFiles = await bundle.getDeletedFiles()
98 for (const file of deletedFiles) {
99 await environment.deleteFile(resolve(options.targetDir, file))
100 }
101 }
102​
103 environment.startStep({
104 id: 'write-framework-files',
105 type: 'file',
106 message: 'Writing framework files...',
107 })
108 await writeFileBundle(options.framework)
109 environment.finishStep('write-framework-files', 'Framework files written')
110​
111 let wroteAddonFiles = false
112 for (const type of ['add-on', 'example', 'toolchain', 'deployment']) {
113 for (const phase of ['setup', 'add-on', 'example']) {
114 for (const addOn of options.chosenAddOns.filter(
115 (addOn) => addOn.phase === phase && addOn.type === type,
116 )) {
117 environment.startStep({
118 id: 'write-addon-files',
119 type: 'file',
120 message: `Writing ${addOn.name} files...`,
121 })
122 await writeFileBundle(addOn)
123 wroteAddonFiles = true
124 }
125 }
126 }
127 if (wroteAddonFiles) {
128 environment.finishStep('write-addon-files', 'Add-on files written')
129 }
130​
131 if (options.starter) {
132 environment.startStep({
133 id: 'write-starter-files',
134 type: 'file',
135 message: 'Writing starter files...',
136 })
137 await writeFileBundle(options.starter)
138 environment.finishStep('write-starter-files', 'Starter files written')
139 }
140​
141 environment.startStep({
142 id: 'write-package-json',
143 type: 'file',
144 message: 'Writing package.json...',
145 })
146 const packageJSON = await resolvePackageJSONLatest(createPackageJSON(options))
147 await writePnpmWorkspace(
148 environment,
149 resolve(options.targetDir, 'pnpm-workspace.yaml'),
150 options.packageManager,
151 packageJSON,
152 { ...context, workspaceWasPresent },
153 )
154 await environment.writeFile(
155 resolve(options.targetDir, './package.json'),
156 JSON.stringify(packageJSON, null, 2),
157 )
158 environment.finishStep('write-package-json', 'Package.json written')
159​
160 environment.startStep({
161 id: 'write-config-file',
162 type: 'file',
163 message: 'Writing config file...',
164 })
165 await writeConfigFileToEnvironment(environment, options)
166 environment.finishStep('write-config-file', 'Config file written')
168​
169async function runCommandsAndInstallDependencies(
170 environment: Environment,
171 options: Options,
172 packageManagerVersion?: string,
173) {
174 const needsBuildApproval =
175 options.chosenAddOns.some((addOn) => addOn.command?.allowBuilds?.length) ||
176 options.starter?.command?.allowBuilds?.length
177 if (
178 options.packageManager === 'pnpm' &&
179 needsBuildApproval &&
180 packageManagerVersion === undefined
181 ) {
182 packageManagerVersion = await detectPnpmVersion(environment, options.targetDir)
183 }
184​
185 const s = environment.spinner()
186​
187 // Setup git
188 if (options.git) {
189 s.start(`Initializing git repository...`)
190 environment.startStep({
191 id: 'initialize-git-repository',
192 type: 'command',
193 message: 'Initializing git repository...',
194 })
195​
196 await setupGit(environment, options.targetDir)
197​
198 environment.finishStep(
199 'initialize-git-repository',
200 'Initialized git repository',
201 )
202 s.stop(`Initialized git repository`)
203 }
204​
205 // Run any special steps for the new add-ons
206 const specialSteps = new Set<string>([])
207 for (const addOn of options.chosenAddOns) {
208 for (const step of addOn.createSpecialSteps || []) {
209 specialSteps.add(step)
210 }
211 }
212 if (specialSteps.size) {
213 await runSpecialSteps(environment, options, Array.from(specialSteps))
214 }
215​
216 // Install dependencies
217 if (options.install !== false) {
218 s.start(`Installing dependencies via ${options.packageManager}...`)
219 environment.startStep({
220 id: 'install-dependencies',
221 type: 'package-manager',
222 message: `Installing dependencies via ${options.packageManager}...`,
223 })
224 await packageManagerInstall(
225 environment,
226 options.targetDir,
227 options.packageManager,
228 )
229 environment.finishStep('install-dependencies', 'Installed dependencies')
230 s.stop(`Installed dependencies`)
231 } else {
232 s.start(`Skipping dependency installation...`)
233 environment.startStep({
234 id: 'skip-dependencies',
235 type: 'info',
236 message: `Skipping dependency installation...`,
237 })
238 environment.finishStep('skip-dependencies', 'Dependency installation skipped')
239 s.stop(`Dependency installation skipped`)
240 }
241​
242 // Run any post-init special steps for the new add-ons
243 const postInitSpecialSteps = new Set<string>([])
244 for (const addOn of options.chosenAddOns) {
245 for (const step of addOn.postInitSpecialSteps || []) {
246 postInitSpecialSteps.add(step)
247 }
248 }
249 if (postInitSpecialSteps.size) {
250 await runSpecialSteps(
251 environment,
252 options,
253 Array.from(postInitSpecialSteps),
254 )
255 }
256​
257 for (const phase of ['setup', 'add-on', 'example']) {
258 for (const addOn of options.chosenAddOns.filter(
259 (addOn) =>
260 addOn.phase === phase && addOn.command && addOn.command.command,
261 )) {
262 s.start(`Running commands for ${addOn.name}...`)
263 const translated = translateExecuteCommand(options.packageManager, {
264 command: addOn.command!.command,
265 args: addOn.command!.args || [],
266 allowBuilds: addOn.command!.allowBuilds,
267 }, packageManagerVersion)
268 const cmd = formatCommand(translated)
269 environment.startStep({
270 id: 'run-commands',
271 type: 'command',
272 message: cmd,
273 })
274 await environment.execute(
275 translated.command,
276 translated.args,
277 options.targetDir,
278 { inherit: true },
279 )
280 environment.finishStep('run-commands', 'Setup commands complete')
281 s.stop(`${addOn.name} commands complete`)
282 }
283 }
284​
285 // Adding starter
286 if (
287 options.starter &&
288 options.starter.command &&
289 options.starter.command.command
290 ) {
291 s.start(`Setting up starter ${options.starter.name}...`)
292 const starterTranslated = translateExecuteCommand(options.packageManager, {
293 command: options.starter.command.command,
294 args: options.starter.command.args || [],
295 allowBuilds: options.starter.command.allowBuilds,
296 }, packageManagerVersion)
297 const cmd = formatCommand(starterTranslated)
298 environment.startStep({
299 id: 'run-starter-command',
300 type: 'command',
301 message: cmd,
302 })
303​
304 await environment.execute(
305 starterTranslated.command,
306 starterTranslated.args,
307 options.targetDir,
308 { inherit: true },
309 )
310​
311 environment.finishStep('run-starter-command', 'Starter command complete')
312 s.stop(`${options.starter.name} commands complete`)
313 }
314​
315 await installShadcnComponents(environment, options.targetDir, options)
316​
317 await setupIntent(environment, options.targetDir, options)
318​
319 if (shouldGenerateRoutes(options)) {
320 s.start(`Generating route tree...`)
321 const command = getPackageManagerScriptCommand(options.packageManager, [
322 'generate-routes',
323 ])
324 const cmd = formatCommand(command)
325 environment.startStep({
326 id: 'generate-routes',
327 type: 'command',
328 message: cmd,
329 })
330 await environment.execute(
331 command.command,
332 command.args,
333 options.targetDir,
334 {
335 inherit: true,
336 },
337 )
338 environment.finishStep('generate-routes', 'Route tree generated')
339 s.stop(`Route tree generated`)
340 }
342​
343function shouldGenerateRoutes(options: Options) {
344 return (
345 options.install !== false &&
346 options.mode === 'file-router' &&
347 (options.framework.id === 'react' || options.framework.id === 'solid')
348 )
350​
351async function seedEnvValues(environment: Environment, options: Options) {
352 const envVarValues = options.envVarValues || {}
353 const entries = Object.entries(envVarValues)
354 if (entries.length === 0) return
355​
356 const envLocalPath = resolve(options.targetDir, '.env.local')
357 if (!environment.exists(envLocalPath)) {
358 return
359 }
360​
361 let envContents = await environment.readFile(envLocalPath)
362 for (const [key, value] of entries) {
363 const escapedValue = value.replace(/\n/g, '\\n')
364 const nextLine = `${key}=${escapedValue}`
365 const pattern = new RegExp(`^${key}=.*$`, 'm')
366​
367 if (pattern.test(envContents)) {
368 envContents = envContents.replace(pattern, nextLine)
369 } else {
370 envContents += `${envContents.endsWith('\n') ? '' : '\n'}${nextLine}\n`
371 }
372 }
373​
374 await environment.writeFile(envLocalPath, envContents)
376​
377async function writeEnvExample(environment: Environment, options: Options) {
378 const envExamplePath = resolve(options.targetDir, '.env.example')
379 const existing = environment.exists(envExamplePath)
380 ? await environment.readFile(envExamplePath)
381 : ''
382​
383 const declared = new Set<string>()
384 for (const match of existing.matchAll(/^([A-Z_][A-Z0-9_]*)=/gm)) {
385 declared.add(match[1])
386 }
387​
388 const sections: Array<string> = []
389 for (const addOn of options.chosenAddOns) {
390 const lines: Array<string> = []
391 for (const envVar of addOn.envVars || []) {
392 if (declared.has(envVar.name)) continue
393 declared.add(envVar.name)
394 if (envVar.description) {
395 const required = envVar.required ? ' (required)' : ''
396 lines.push(`# ${envVar.description}${required}`)
397 }
398 lines.push(`${envVar.name}=`)
399 }
400 if (lines.length > 0) {
401 sections.push(`# ${addOn.name}\n${lines.join('\n')}`)
402 }
403 }
404​
405 if (sections.length === 0) return
406​
407 const additions = sections.join('\n\n')
408 const newContent = existing
409 ? `${existing.trimEnd()}\n\n${additions}\n`
410 : `${additions}\n`
411​
412 await environment.writeFile(envExamplePath, newContent)
414​
415const SHIPPING_CATEGORIES = new Set(['auth', 'database', 'orm', 'deploy'])
416​
417function buildNextSteps(options: Options): string {
418 const collectedEnv = new Set(Object.keys(options.envVarValues || {}))
419 const listedEnvVars = new Set<string>()
420 const envVarLines: Array<string> = []
421 const docLines: Array<string> = []
422​
423 for (const addOn of options.chosenAddOns) {
424 if (addOn.link && addOn.category && SHIPPING_CATEGORIES.has(addOn.category)) {
425 docLines.push(` • ${addOn.name} (${addOn.category}) — ${addOn.link}`)
426 }
427​
428 for (const envVar of addOn.envVars || []) {
429 if (listedEnvVars.has(envVar.name)) continue
430 listedEnvVars.add(envVar.name)
431 const required = envVar.required ? ' (required)' : ''
432 const status = collectedEnv.has(envVar.name)
433 ? ' — already set from your input'
434 : ' — needs a value'
435 const desc = envVar.description ? ` — ${envVar.description}` : ''
436 envVarLines.push(` • ${envVar.name}${required}${desc}${status}`)
437 }
438 }
439​
440 const sections: Array<string> = []
441 if (envVarLines.length > 0) {
442 sections.push(
443 `Environment variables (review/fill in .env.local before deploying):\n${envVarLines.join('\n')}`,
444 )
445 }
446 if (docLines.length > 0) {
447 sections.push(`Docs for the integrations you picked:\n${docLines.join('\n')}`)
448 }
449 if (options.intent) {
450 if (options.install === false) {
451 const installCommand = formatCommand(
452 getPackageManagerInstallCommand(options.packageManager),
453 )
454 sections.push(
455 `TanStack Intent setup was skipped because dependency installation was skipped.\nInstall dependencies, then generate agent guidance:\n % ${installCommand}\n % ${intentCommand(options.packageManager, ['install', '--map'])}`,
456 )
457 } else {
458 sections.push(
459 `Working with an AI agent? Your agent config (AGENTS.md / CLAUDE.md) was wired up by TanStack Intent\nso your agent can discover skills for the libraries you installed, on demand:\n • ${intentCommand(options.packageManager, ['list'])}\n • ${intentCommand(options.packageManager, ['load', '<package>#<skill>'])}\nTry asking your agent:\n • "migrate this Next.js page to TanStack Start"\n • "add a protected /dashboard route"\n • "show me how to use TanStack Router search params"`,
460 )
461 }
462 }
463​
464 return sections.length > 0 ? `\nNext steps:\n\n${sections.join('\n\n')}\n` : ''
466​
467function report(environment: Environment, options: Options) {
468 const warnings: Array<string> = []
469 for (const addOn of options.chosenAddOns) {
470 if (addOn.warning) {
471 warnings.push(addOn.warning)
472 }
473 }
474​
475 if (warnings.length > 0) {
476 environment.warn('Warnings', warnings.join('\n'))
477 }
478​
479 // Format errors
480 let errorStatement = ''
481 if (environment.getErrors().length) {
482 errorStatement = `
483​
484Errors were encountered during the creation of your app:
485​
486${environment.getErrors().join('\n')}`
487 }
488​
489 // Check if we created in current directory (user specified ".")
490 const isCurrentDirectory =
491 resolve(options.targetDir) === resolve(process.cwd())
492 const locationMessage = isCurrentDirectory
493 ? `Your ${environment.appName} app is ready.`
494 : `Your ${environment.appName} app is ready in '${basename(options.targetDir)}'.`
495 const cdInstruction = isCurrentDirectory
496 ? ''
497 : `% cd ${options.projectName}
499​
500 const nextSteps = buildNextSteps(options)
501 const readmeDescription =
502 options.projectPreset === 'blank'
503 ? 'running, building, adding routes, and selected integrations.'
504 : 'testing, styling, adding routes, etc.'
505​
506 // Use the force luke! :)
507 environment.outro(
508 `${locationMessage}
509​
510Use the following commands to start your app:
511${cdInstruction}% ${formatCommand(
512 getPackageManagerScriptCommand(options.packageManager, ['dev']),
513 )}
514${nextSteps}
515Please read the README.md file for information on ${readmeDescription}${errorStatement}`,
516 )
518​
519export async function createApp(
520 environment: Environment,
521 options: Options,
522 context: { existingProject?: boolean; packageManagerVersion?: string } = {},
523) {
524 validatePackageManagerSupport(options.packageManager, options.chosenAddOns)
525 const effectiveOptions = stripExamplesFromOptions(normalizeAndValidateBundlerOptions(options))
526​
527 environment.startRun()
528 await writeFiles(environment, effectiveOptions, context)
529 await seedEnvValues(environment, effectiveOptions)
530 await writeEnvExample(environment, effectiveOptions)
531 await runCommandsAndInstallDependencies(environment, effectiveOptions, context.packageManagerVersion)
532 environment.finishRun()
533​
534 report(environment, effectiveOptions)