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

edge-create-app.ts

607 lines18.2 KB

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