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

edge-create-app.ts

664 lines20.0 KB

1import { createPackageJSON } from './edge-package-json.js'
2import { writePnpmWorkspace } from './pnpm-workspace.js'
3import { createTemplateFile } from './edge-template-file.js'
4import { formatCommand } from './utils.js'
5import { isBase64, isDemoFilePath } from './edge-file-helpers.js'
6import { basenamePath, joinPaths, normalizePath } from './edge-path.js'
7import { resolvePackageJSONLatest } from './npm-resolver.js'
8import { writeConfigFileToEnvironment } from './edge-config-file.js'
9import {
10 INTENT_PACKAGE,
11 detectPnpmVersion,
12 getPackageManagerExecuteCommand,
13 getPackageManagerInstallCommand,
14 getPackageManagerScriptCommand,
15 intentCommand,
16 packageManagerInstall,
17 translateExecuteCommand,
18 validatePackageManagerSupport,
19} from './package-manager.js'
20import { normalizeAndValidateBundlerOptions } from './build-tools.js'
21​
22import type { Environment, FileBundleHandler, Options } from './types.js'
23​
24function stripExamplesFromOptions(options: Options): Options {
25 const includeExamples =
26 options.projectPreset !== 'blank' && options.includeExamples !== false
27​
28 if (includeExamples) {
29 return options
30 }
31​
32 const chosenAddOns = options.chosenAddOns
33 .filter((addOn) => addOn.type !== 'example')
34 .map((addOn) => {
35 const filteredRoutes = (addOn.routes || []).filter(
36 (route) =>
37 !isDemoFilePath(route.path) &&
38 !(route.url && route.url.startsWith('/demo')),
39 )
40​
41 const filteredIntegrations = (addOn.integrations || []).filter(
42 (integration) => !isDemoFilePath(integration.path),
43 )
44​
45 return {
46 ...addOn,
47 routes: filteredRoutes,
48 integrations: filteredIntegrations,
49 getFiles: async () => {
50 const files = await addOn.getFiles()
51 return files.filter((file) => !isDemoFilePath(file))
52 },
53 getDeletedFiles: async () => {
54 const deletedFiles = await addOn.getDeletedFiles()
55 return deletedFiles.filter((file) => !isDemoFilePath(file))
56 },
57 }
58 })
59​
60 return {
61 ...options,
62 includeExamples: false,
63 chosenAddOns,
64 }
66​
67async function writeFiles(
68 environment: Environment,
69 options: Options,
70 context: { existingProject?: boolean } = {},
71) {
72 const workspaceWasPresent = environment.exists(
73 joinPaths(options.targetDir, 'pnpm-workspace.yaml'),
74 )
75 const templateFileFromContent = createTemplateFile(environment, options)
76​
77 async function writeFileBundle(bundle: FileBundleHandler) {
78 const files = await bundle.getFiles()
79​
80 for (const file of files) {
81 const contents = await bundle.getFileContents(file)
82​
83 if (isBase64(contents)) {
84 await environment.writeFileBase64(
85 joinPaths(options.targetDir, file),
86 contents,
87 )
88 } else {
89 await templateFileFromContent(file, contents)
90 }
91 }
92​
93 const deletedFiles = await bundle.getDeletedFiles()
94 for (const file of deletedFiles) {
95 await environment.deleteFile(joinPaths(options.targetDir, file))
96 }
97 }
98​
99 environment.startStep({
100 id: 'write-framework-files',
101 type: 'file',
102 message: 'Writing framework files...',
103 })
104 await writeFileBundle(options.framework)
105 environment.finishStep('write-framework-files', 'Framework files written')
106​
107 let wroteAddonFiles = false
108 for (const type of ['add-on', 'example', 'toolchain', 'deployment']) {
109 for (const phase of ['setup', 'add-on', 'example']) {
110 for (const addOn of options.chosenAddOns.filter(
111 (addOn) => addOn.phase === phase && addOn.type === type,
112 )) {
113 environment.startStep({
114 id: 'write-addon-files',
115 type: 'file',
116 message: `Writing ${addOn.name} files...`,
117 })
118 await writeFileBundle(addOn)
119 wroteAddonFiles = true
120 }
121 }
122 }
123 if (wroteAddonFiles) {
124 environment.finishStep('write-addon-files', 'Add-on files written')
125 }
126​
127 if (options.starter) {
128 environment.startStep({
129 id: 'write-starter-files',
130 type: 'file',
131 message: 'Writing starter files...',
132 })
133 await writeFileBundle(options.starter)
134 environment.finishStep('write-starter-files', 'Starter files written')
135 }
136​
137 environment.startStep({
138 id: 'write-package-json',
139 type: 'file',
140 message: 'Writing package.json...',
141 })
142 const packageJSON = await resolvePackageJSONLatest(createPackageJSON(options))
143 await writePnpmWorkspace(
144 environment,
145 joinPaths(options.targetDir, 'pnpm-workspace.yaml'),
146 options.packageManager,
147 packageJSON,
148 { ...context, workspaceWasPresent },
149 )
150 await environment.writeFile(
151 joinPaths(options.targetDir, './package.json'),
152 JSON.stringify(packageJSON, null, 2),
153 )
154 environment.finishStep('write-package-json', 'Package.json written')
155​
156 environment.startStep({
157 id: 'write-config-file',
158 type: 'file',
159 message: 'Writing config file...',
160 })
161 await writeConfigFileToEnvironment(environment, options)
162 environment.finishStep('write-config-file', 'Config file written')
164​
165async function runSpecialSteps(
166 environment: Environment,
167 options: Options,
168 specialSteps: Array<string>,
169) {
170 if (!specialSteps.length) {
171 return
172 }
173​
174 environment.startStep({
175 id: 'special-steps',
176 type: 'command',
177 message: 'Running special steps...',
178 })
179​
180 for (const step of specialSteps) {
181 if (step === 'rimraf-node-modules') {
182 await environment.rimraf(joinPaths(options.targetDir, 'node_modules'))
183 for (const lockFile of [
184 'package-lock.json',
185 'yarn.lock',
186 'pnpm-lock.yaml',
187 ]) {
188 const lockFilePath = joinPaths(options.targetDir, lockFile)
189 if (environment.exists(lockFilePath)) {
190 await environment.deleteFile(lockFilePath)
191 }
192 }
193 continue
194 }
195​
196 if (step === 'post-init-script') {
197 const packageJsonPath = joinPaths(options.targetDir, 'package.json')
198 if (!environment.exists(packageJsonPath)) {
199 environment.warn(
200 'Warning',
201 'No package.json found, skipping post-create-init script',
202 )
203 continue
204 }
205​
206 const packageJson = JSON.parse(await environment.readFile(packageJsonPath))
207 const postCreateInit = packageJson.scripts?.['post-create-init']
208 if (postCreateInit) {
209 const { command, args } = getPackageManagerScriptCommand(
210 options.packageManager,
211 ['post-create-init'],
212 )
213 await environment.execute(command, args, options.targetDir, {
214 inherit: true,
215 })
216 }
217 continue
218 }
219​
220 environment.error(`Special step ${step} not found`)
221 }
222​
223 environment.finishStep('special-steps', 'Special steps complete')
225​
226async function installShadcnComponents(
227 environment: Environment,
228 targetDir: string,
229 options: Options,
230) {
231 if (!options.chosenAddOns.find((a) => a.id === 'shadcn')) {
232 return
233 }
234​
235 const shadcnComponents = new Set<string>()
236 for (const addOn of options.chosenAddOns) {
237 if (addOn.shadcnComponents) {
238 for (const component of addOn.shadcnComponents) {
239 shadcnComponents.add(component)
240 }
241 }
242 }
243 if (options.starter?.shadcnComponents) {
244 for (const component of options.starter.shadcnComponents) {
245 shadcnComponents.add(component)
246 }
247 }
248​
249 if (shadcnComponents.size > 0) {
250 environment.startStep({
251 id: 'install-shadcn-components',
252 type: 'command',
253 message: `Installing shadcn components (${Array.from(shadcnComponents).join(', ')})...`,
254 })
255​
256 const { command, args } = getPackageManagerExecuteCommand(
257 options.packageManager,
258 'shadcn@latest',
259 ['add', '--silent', '--yes', ...Array.from(shadcnComponents)],
260 )
261 await environment.execute(command, args, normalizePath(targetDir))
262​
263 environment.finishStep(
264 'install-shadcn-components',
265 'Shadcn components installed',
266 )
267 }
269​
270async function setupIntent(
271 environment: Environment,
272 targetDir: string,
273 options: Options,
274) {
275 if (!options.intent) {
276 return
277 }
278​
279 if (options.install === false) {
280 environment.startStep({
281 id: 'setup-intent',
282 type: 'info',
283 message: 'Skipping TanStack Intent setup...',
284 })
285 environment.finishStep(
286 'setup-intent',
287 'TanStack Intent setup skipped: dependencies not installed',
288 )
289 return
290 }
291​
292 environment.startStep({
293 id: 'setup-intent',
294 type: 'command',
295 message: 'Setting up TanStack Intent skill discovery...',
296 })
297​
298 const { command, args } = getPackageManagerExecuteCommand(
299 options.packageManager,
300 INTENT_PACKAGE,
301 ['install'],
302 )
303 await environment.execute(command, args, normalizePath(targetDir))
304 environment.finishStep('setup-intent', 'TanStack Intent configured')
306​
307async function runCommandsAndInstallDependencies(
308 environment: Environment,
309 options: Options,
310 packageManagerVersion?: string,
311) {
312 const needsBuildApproval =
313 options.chosenAddOns.some((addOn) => addOn.command?.allowBuilds?.length) ||
314 options.starter?.command?.allowBuilds?.length
315 if (
316 options.packageManager === 'pnpm' &&
317 needsBuildApproval &&
318 packageManagerVersion === undefined
319 ) {
320 packageManagerVersion = await detectPnpmVersion(environment, options.targetDir)
321 }
322​
323 const s = environment.spinner()
324​
325 if (options.git) {
326 s.start('Initializing git repository...')
327 environment.startStep({
328 id: 'initialize-git-repository',
329 type: 'command',
330 message: 'Initializing git repository...',
331 })
332​
333 await environment.execute('git', ['init'], normalizePath(options.targetDir))
334​
335 environment.finishStep(
336 'initialize-git-repository',
337 'Initialized git repository',
338 )
339 s.stop('Initialized git repository')
340 }
341​
342 const specialSteps = new Set<string>()
343 for (const addOn of options.chosenAddOns) {
344 for (const step of addOn.createSpecialSteps || []) {
345 specialSteps.add(step)
346 }
347 }
348 if (specialSteps.size) {
349 await runSpecialSteps(environment, options, Array.from(specialSteps))
350 }
351​
352 if (options.install !== false) {
353 s.start(`Installing dependencies via ${options.packageManager}...`)
354 environment.startStep({
355 id: 'install-dependencies',
356 type: 'package-manager',
357 message: `Installing dependencies via ${options.packageManager}...`,
358 })
359 await packageManagerInstall(
360 environment,
361 options.targetDir,
362 options.packageManager,
363 )
364 environment.finishStep('install-dependencies', 'Installed dependencies')
365 s.stop('Installed dependencies')
366 } else {
367 s.start('Skipping dependency installation...')
368 environment.startStep({
369 id: 'skip-dependencies',
370 type: 'info',
371 message: 'Skipping dependency installation...',
372 })
373 environment.finishStep('skip-dependencies', 'Dependency installation skipped')
374 s.stop('Dependency installation skipped')
375 }
376​
377 const postInitSpecialSteps = new Set<string>()
378 for (const addOn of options.chosenAddOns) {
379 for (const step of addOn.postInitSpecialSteps || []) {
380 postInitSpecialSteps.add(step)
381 }
382 }
383 if (postInitSpecialSteps.size) {
384 await runSpecialSteps(
385 environment,
386 options,
387 Array.from(postInitSpecialSteps),
388 )
389 }
390​
391 for (const phase of ['setup', 'add-on', 'example']) {
392 for (const addOn of options.chosenAddOns.filter(
393 (addOn) =>
394 addOn.phase === phase && addOn.command && addOn.command.command,
395 )) {
396 s.start(`Running commands for ${addOn.name}...`)
397 const translated = translateExecuteCommand(options.packageManager, {
398 command: addOn.command!.command,
399 args: addOn.command!.args || [],
400 allowBuilds: addOn.command!.allowBuilds,
401 }, packageManagerVersion)
402 const cmd = formatCommand(translated)
403 environment.startStep({
404 id: 'run-commands',
405 type: 'command',
406 message: cmd,
407 })
408 await environment.execute(
409 translated.command,
410 translated.args,
411 options.targetDir,
412 { inherit: true },
413 )
414 environment.finishStep('run-commands', 'Setup commands complete')
415 s.stop(`${addOn.name} commands complete`)
416 }
417 }
418​
419 if (
420 options.starter &&
421 options.starter.command &&
422 options.starter.command.command
423 ) {
424 s.start(`Setting up starter ${options.starter.name}...`)
425 const starterTranslated = translateExecuteCommand(options.packageManager, {
426 command: options.starter.command.command,
427 args: options.starter.command.args || [],
428 allowBuilds: options.starter.command.allowBuilds,
429 }, packageManagerVersion)
430 const cmd = formatCommand(starterTranslated)
431 environment.startStep({
432 id: 'run-starter-command',
433 type: 'command',
434 message: cmd,
435 })
436​
437 await environment.execute(
438 starterTranslated.command,
439 starterTranslated.args,
440 options.targetDir,
441 { inherit: true },
442 )
443​
444 environment.finishStep('run-starter-command', 'Starter command complete')
445 s.stop(`${options.starter.name} commands complete`)
446 }
447​
448 await installShadcnComponents(environment, options.targetDir, options)
449 await setupIntent(environment, options.targetDir, options)
450​
451 if (shouldGenerateRoutes(options)) {
452 s.start('Generating route tree...')
453 const command = getPackageManagerScriptCommand(options.packageManager, [
454 'generate-routes',
455 ])
456 const cmd = formatCommand(command)
457 environment.startStep({
458 id: 'generate-routes',
459 type: 'command',
460 message: cmd,
461 })
462 await environment.execute(
463 command.command,
464 command.args,
465 options.targetDir,
466 {
467 inherit: true,
468 },
469 )
470 environment.finishStep('generate-routes', 'Route tree generated')
471 s.stop('Route tree generated')
472 }
474​
475function shouldGenerateRoutes(options: Options) {
476 return (
477 options.install !== false &&
478 options.mode === 'file-router' &&
479 (options.framework.id === 'react' || options.framework.id === 'solid')
480 )
482​
483async function seedEnvValues(environment: Environment, options: Options) {
484 const envVarValues = options.envVarValues || {}
485 const entries = Object.entries(envVarValues)
486 if (entries.length === 0) return
487​
488 const envLocalPath = joinPaths(options.targetDir, '.env.local')
489 if (!environment.exists(envLocalPath)) {
490 return
491 }
492​
493 let envContents = await environment.readFile(envLocalPath)
494 for (const [key, value] of entries) {
495 const escapedValue = value.replace(/\n/g, '\\n')
496 const nextLine = `${key}=${escapedValue}`
497 const pattern = new RegExp(`^${key}=.*$`, 'm')
498​
499 if (pattern.test(envContents)) {
500 envContents = envContents.replace(pattern, nextLine)
501 } else {
502 envContents += `${envContents.endsWith('\n') ? '' : '\n'}${nextLine}\n`
503 }
504 }
505​
506 await environment.writeFile(envLocalPath, envContents)
508​
509async function writeEnvExample(environment: Environment, options: Options) {
510 const envExamplePath = joinPaths(options.targetDir, '.env.example')
511 const existing = environment.exists(envExamplePath)
512 ? await environment.readFile(envExamplePath)
513 : ''
514​
515 const declared = new Set<string>()
516 for (const match of existing.matchAll(/^([A-Z_][A-Z0-9_]*)=/gm)) {
517 declared.add(match[1])
518 }
519​
520 const sections: Array<string> = []
521 for (const addOn of options.chosenAddOns) {
522 const lines: Array<string> = []
523 for (const envVar of addOn.envVars || []) {
524 if (declared.has(envVar.name)) continue
525 declared.add(envVar.name)
526 if (envVar.description) {
527 const required = envVar.required ? ' (required)' : ''
528 lines.push(`# ${envVar.description}${required}`)
529 }
530 lines.push(`${envVar.name}=`)
531 }
532 if (lines.length > 0) {
533 sections.push(`# ${addOn.name}\n${lines.join('\n')}`)
534 }
535 }
536​
537 if (sections.length === 0) return
538​
539 const additions = sections.join('\n\n')
540 const newContent = existing
541 ? `${existing.trimEnd()}\n\n${additions}\n`
542 : `${additions}\n`
543​
544 await environment.writeFile(envExamplePath, newContent)
546​
547const SHIPPING_CATEGORIES = new Set(['auth', 'database', 'orm', 'deploy'])
548​
549function buildNextSteps(options: Options): string {
550 const collectedEnv = new Set(Object.keys(options.envVarValues || {}))
551 const listedEnvVars = new Set<string>()
552 const envVarLines: Array<string> = []
553 const docLines: Array<string> = []
554​
555 for (const addOn of options.chosenAddOns) {
556 if (addOn.link && addOn.category && SHIPPING_CATEGORIES.has(addOn.category)) {
557 docLines.push(` - ${addOn.name} (${addOn.category}): ${addOn.link}`)
558 }
559​
560 for (const envVar of addOn.envVars || []) {
561 if (listedEnvVars.has(envVar.name)) continue
562 listedEnvVars.add(envVar.name)
563 const required = envVar.required ? ' (required)' : ''
564 const status = collectedEnv.has(envVar.name)
565 ? ' - already set from your input'
566 : ' - needs a value'
567 const desc = envVar.description ? ` - ${envVar.description}` : ''
568 envVarLines.push(` - ${envVar.name}${required}${desc}${status}`)
569 }
570 }
571​
572 const sections: Array<string> = []
573 if (envVarLines.length > 0) {
574 sections.push(
575 `Environment variables (review/fill in .env.local before deploying):\n${envVarLines.join('\n')}`,
576 )
577 }
578 if (docLines.length > 0) {
579 sections.push(`Docs for the integrations you picked:\n${docLines.join('\n')}`)
580 }
581 if (options.intent) {
582 if (options.install === false) {
583 const installCommand = formatCommand(
584 getPackageManagerInstallCommand(options.packageManager),
585 )
586 sections.push(
587 `TanStack Intent setup was skipped because dependency installation was skipped.\nInstall dependencies, then generate agent guidance:\n % ${installCommand}\n % ${intentCommand(options.packageManager, ['install', '--map'])}`,
588 )
589 } else {
590 sections.push(
591 `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"`,
592 )
593 }
594 }
595​
596 return sections.length > 0 ? `\nNext steps:\n\n${sections.join('\n\n')}\n` : ''
598​
599function report(environment: Environment, options: Options) {
600 const warnings: Array<string> = []
601 for (const addOn of options.chosenAddOns) {
602 if (addOn.warning) {
603 warnings.push(addOn.warning)
604 }
605 }
606​
607 if (warnings.length > 0) {
608 environment.warn('Warnings', warnings.join('\n'))
609 }
610​
611 let errorStatement = ''
612 if (environment.getErrors().length) {
613 errorStatement = `
614​
615Errors were encountered during the creation of your app:
616​
617${environment.getErrors().join('\n')}`
618 }
619​
620 const targetDir = normalizePath(options.targetDir)
621 const isCurrentDirectory = targetDir === '.'
622 const locationMessage = isCurrentDirectory
623 ? `Your ${environment.appName} app is ready.`
624 : `Your ${environment.appName} app is ready in '${basenamePath(targetDir)}'.`
625 const cdInstruction = isCurrentDirectory
626 ? ''
627 : `% cd ${options.projectName}
629​
630 const nextSteps = buildNextSteps(options)
631 const readmeDescription =
632 options.projectPreset === 'blank'
633 ? 'running, building, adding routes, and selected integrations.'
634 : 'testing, styling, adding routes, etc.'
635​
636 environment.outro(
637 `${locationMessage}
638​
639Use the following commands to start your app:
640${cdInstruction}% ${formatCommand(
641 getPackageManagerScriptCommand(options.packageManager, ['dev']),
642 )}
643${nextSteps}
644Please read the README.md file for information on ${readmeDescription}${errorStatement}`,
645 )
647​
648export async function createApp(
649 environment: Environment,
650 options: Options,
651 context: { existingProject?: boolean; packageManagerVersion?: string } = {},
652) {
653 validatePackageManagerSupport(options.packageManager, options.chosenAddOns)
654 const effectiveOptions = stripExamplesFromOptions(normalizeAndValidateBundlerOptions(options))
655​
656 environment.startRun()
657 await writeFiles(environment, effectiveOptions, context)
658 await seedEnvValues(environment, effectiveOptions)
659 await writeEnvExample(environment, effectiveOptions)
660 await runCommandsAndInstallDependencies(environment, effectiveOptions, context.packageManagerVersion)
661 environment.finishRun()
662​
663 report(environment, effectiveOptions)