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