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

cli.ts

431 lines12.6 KB

1import fs from 'node:fs'
2import { resolve } from 'node:path'
3import { Command, InvalidArgumentError } from 'commander'
4import { intro, log } from '@clack/prompts'
5import chalk from 'chalk'
6import semver from 'semver'
7​
8import {
9 SUPPORTED_PACKAGE_MANAGERS,
10 addToApp,
11 compileAddOn,
12 compileStarter,
13 createApp,
14 createSerializedOptions,
15 getAllAddOns,
16 getFrameworkById,
17 getFrameworkByName,
18 getFrameworks,
19 initAddOn,
20 initStarter,
21} from '@tanstack/cta-engine'
22​
23import { launchUI } from '@tanstack/cta-ui'
24​
25import { runMCPServer } from './mcp.js'
26​
27import { promptForAddOns, promptForCreateOptions } from './options.js'
28import { normalizeOptions } from './command-line.js'
29​
30import { createUIEnvironment } from './ui-environment.js'
31import { convertTemplateToMode } from './utils.js'
32​
33import type { CliOptions, TemplateOptions } from './types.js'
34import type { Options, PackageManager } from '@tanstack/cta-engine'
35​
36// This CLI assumes that all of the registered frameworks have the same set of toolchains, modes, etc.
37​
38export function cli({
39 name,
40 appName,
41 forcedMode,
42 forcedAddOns = [],
43 defaultTemplate = 'javascript',
44 defaultFramework,
45 craCompatible = false,
46 webBase,
47}: {
48 name: string
49 appName: string
50 forcedMode?: string
51 forcedAddOns?: Array<string>
52 defaultTemplate?: TemplateOptions
53 defaultFramework?: string
54 craCompatible?: boolean
55 webBase?: string
56}) {
57 const environment = createUIEnvironment(appName, false)
58​
59 const program = new Command()
60​
61 const availableFrameworks = getFrameworks().map((f) => f.name)
62​
63 const toolchains = new Set<string>()
64 for (const framework of getFrameworks()) {
65 for (const addOn of framework.getAddOns()) {
66 if (addOn.type === 'toolchain') {
67 toolchains.add(addOn.id)
68 }
69 }
70 }
71​
72 let defaultMode: string | undefined = forcedMode
73 const supportedModes = new Set<string>()
74 for (const framework of getFrameworks()) {
75 for (const mode of Object.keys(framework.supportedModes)) {
76 supportedModes.add(mode)
77 }
78 }
79 if (defaultMode && !supportedModes.has(defaultMode)) {
80 throw new InvalidArgumentError(
81 `Invalid mode: ${defaultMode}. The following are allowed: ${Array.from(
82 supportedModes,
83 ).join(', ')}`,
84 )
85 }
86 if (supportedModes.size < 2) {
87 defaultMode = Array.from(supportedModes)[0]
88 }
89​
90 program.name(name).description(`CLI to create a new ${appName} application`)
91​
92 program
93 .command('pin-versions')
94 .description('Pin versions of the TanStack libraries')
95 .action(async () => {
96 if (!fs.existsSync('package.json')) {
97 console.error('package.json not found')
98 return
99 }
100 const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'))
101​
102 const packages: Record<string, string> = {
103 '@tanstack/react-router': '',
104 '@tanstack/router-generator': '',
105 '@tanstack/react-router-devtools': '',
106 '@tanstack/react-start': '',
107 '@tanstack/react-start-config': '',
108 '@tanstack/router-plugin': '',
109 '@tanstack/react-start-client': '',
110 '@tanstack/react-start-plugin': '1.115.0',
111 '@tanstack/react-start-server': '',
112 '@tanstack/start-server-core': '1.115.0',
113 }
114​
115 function sortObject(obj: Record<string, string>): Record<string, string> {
116 return Object.keys(obj)
117 .sort()
118 .reduce<Record<string, string>>((acc, key) => {
119 acc[key] = obj[key]
120 return acc
121 }, {})
122 }
123​
124 if (!packageJson.dependencies['@tanstack/react-start']) {
125 console.error('@tanstack/react-start not found in dependencies')
126 return
127 }
128 let changed = 0
129 const startVersion = packageJson.dependencies[
130 '@tanstack/react-start'
131 ].replace(/^\^/, '')
132 for (const pkg of Object.keys(packages)) {
133 if (!packageJson.dependencies[pkg]) {
134 packageJson.dependencies[pkg] = packages[pkg].length
135 ? semver.maxSatisfying(
136 [startVersion, packages[pkg]],
137 `^${packages[pkg]}`,
138 )!
139 : startVersion
140 changed++
141 } else {
142 if (packageJson.dependencies[pkg].startsWith('^')) {
143 packageJson.dependencies[pkg] = packageJson.dependencies[
144 pkg
145 ].replace(/^\^/, '')
146 changed++
147 }
148 }
149 }
150 packageJson.dependencies = sortObject(packageJson.dependencies)
151 if (changed > 0) {
152 fs.writeFileSync('package.json', JSON.stringify(packageJson, null, 2))
153 console.log(
154 `${changed} packages updated.
155​
156Remove your node_modules directory and package lock file and re-install.`,
157 )
158 } else {
159 console.log(
160 'No changes needed. The relevant TanStack packages are already pinned.',
161 )
162 }
163 })
164​
165 program
166 .command('add')
167 .argument(
168 '[add-on...]',
169 'Name of the add-ons (or add-ons separated by spaces or commas)',
170 )
171 .option('--forced', 'Force the add-on to be added', false)
172 .option('--ui', 'Add with the UI')
173 .action(async (addOns: Array<string>) => {
174 const parsedAddOns: Array<string> = []
175 for (const addOn of addOns) {
176 if (addOn.includes(',') || addOn.includes(' ')) {
177 parsedAddOns.push(
178 ...addOn.split(/[\s,]+/).map((addon) => addon.trim()),
179 )
180 } else {
181 parsedAddOns.push(addOn.trim())
182 }
183 }
184 if (program.opts().ui) {
185 launchUI({
186 mode: 'add',
187 addOns: parsedAddOns,
188 projectPath: resolve(process.cwd()),
189 forcedRouterMode: defaultMode,
190 forcedAddOns,
191 environmentFactory: () => createUIEnvironment(appName, false),
192 webBase,
193 })
194 } else if (parsedAddOns.length < 1) {
195 const addOns = await promptForAddOns()
196 if (addOns.length) {
197 await addToApp(environment, addOns, resolve(process.cwd()), {
198 forced: program.opts().forced,
199 })
200 }
201 } else {
202 await addToApp(environment, parsedAddOns, resolve(process.cwd()), {
203 forced: program.opts().forced,
204 })
205 }
206 })
207​
208 const addOnCommand = program.command('add-on')
209 addOnCommand
210 .command('init')
211 .description('Initialize an add-on from the current project')
212 .action(async () => {
213 await initAddOn(environment)
214 })
215 addOnCommand
216 .command('compile')
217 .description('Update add-on from the current project')
218 .action(async () => {
219 await compileAddOn(environment)
220 })
221​
222 const starterCommand = program.command('starter')
223 starterCommand
224 .command('init')
225 .description('Initialize a project starter from the current project')
226 .action(async () => {
227 await initStarter(environment)
228 })
229 starterCommand
230 .command('compile')
231 .description('Compile the starter JSON file for the current project')
232 .action(async () => {
233 await compileStarter(environment)
234 })
235​
236 program.argument('[project-name]', 'name of the project')
237​
238 if (!defaultMode && craCompatible) {
239 program.option<'typescript' | 'javascript' | 'file-router'>(
240 '--template <type>',
241 'project template (typescript, javascript, file-router)',
242 (value) => {
243 if (
244 value !== 'typescript' &&
245 value !== 'javascript' &&
246 value !== 'file-router'
247 ) {
248 throw new InvalidArgumentError(
249 `Invalid template: ${value}. Only the following are allowed: typescript, javascript, file-router`,
250 )
251 }
252 return value
253 },
254 )
255 }
256​
257 if (!defaultFramework) {
258 program.option<string>(
259 '--framework <type>',
260 `project framework (${availableFrameworks.join(', ')})`,
261 (value) => {
262 if (
263 !availableFrameworks.some(
264 (f) => f.toLowerCase() === value.toLowerCase(),
265 )
266 ) {
267 throw new InvalidArgumentError(
268 `Invalid framework: ${value}. Only the following are allowed: ${availableFrameworks.join(', ')}`,
269 )
270 }
271 return value
272 },
273 defaultFramework || 'React',
274 )
275 }
276​
277 program
278 .option(
279 '--starter [url]',
280 'initialize this project from a starter URL',
281 false,
282 )
283 .option<PackageManager>(
284 `--package-manager <${SUPPORTED_PACKAGE_MANAGERS.join('|')}>`,
285 `Explicitly tell the CLI to use this package manager`,
286 (value) => {
287 if (!SUPPORTED_PACKAGE_MANAGERS.includes(value as PackageManager)) {
288 throw new InvalidArgumentError(
289 `Invalid package manager: ${value}. The following are allowed: ${SUPPORTED_PACKAGE_MANAGERS.join(
290 ', ',
291 )}`,
292 )
293 }
294 return value as PackageManager
295 },
296 )
297​
298 if (toolchains.size > 0) {
299 program.option<string>(
300 `--toolchain <${Array.from(toolchains).join('|')}>`,
301 `Explicitly tell the CLI to use this toolchain`,
302 (value) => {
303 if (!toolchains.has(value)) {
304 throw new InvalidArgumentError(
305 `Invalid toolchain: ${value}. The following are allowed: ${Array.from(
306 toolchains,
307 ).join(', ')}`,
308 )
309 }
310 return value
311 },
312 )
313 }
314​
315 program
316 .option('--interactive', 'interactive mode', false)
317 .option('--tailwind', 'add Tailwind CSS', false)
318 .option<Array<string> | boolean>(
319 '--add-ons [...add-ons]',
320 'pick from a list of available add-ons (comma separated list)',
321 (value: string) => {
322 let addOns: Array<string> | boolean = !!value
323 if (typeof value === 'string') {
324 addOns = value.split(',').map((addon) => addon.trim())
325 }
326 return addOns
327 },
328 )
329 .option('--list-add-ons', 'list all available add-ons', false)
330 .option('--no-git', 'do not create a git repository')
331 .option(
332 '--target-dir <path>',
333 'the target directory for the application root',
334 )
335 .option('--mcp', 'run the MCP server', false)
336 .option('--mcp-sse', 'run the MCP server in SSE mode', false)
337 .option('--ui', 'Add with the UI')
338​
339 program.action(async (projectName: string, options: CliOptions) => {
340 if (options.listAddOns) {
341 const addOns = await getAllAddOns(
342 getFrameworkByName(options.framework || defaultFramework || 'React')!,
343 defaultMode ||
344 convertTemplateToMode(options.template || defaultTemplate),
345 )
346 for (const addOn of addOns.filter((a) => !forcedAddOns.includes(a.id))) {
347 console.log(`${chalk.bold(addOn.id)}: ${addOn.description}`)
348 }
349 } else if (options.mcp || options.mcpSse) {
350 await runMCPServer(!!options.mcpSse, {
351 forcedMode: defaultMode,
352 forcedAddOns,
353 appName,
354 })
355 } else {
356 try {
357 const cliOptions = {
358 projectName,
359 ...options,
360 } as CliOptions
361​
362 cliOptions.framework = getFrameworkByName(
363 options.framework || defaultFramework || 'React',
364 )!.id
365​
366 if (defaultMode) {
367 cliOptions.template = defaultMode as TemplateOptions
368 }
369​
370 let finalOptions: Options | undefined
371 if (cliOptions.interactive) {
372 cliOptions.addOns = true
373 } else {
374 finalOptions = await normalizeOptions(
375 cliOptions,
376 defaultMode,
377 forcedAddOns,
378 )
379 }
380​
381 if (options.ui) {
382 const optionsFromCLI = await normalizeOptions(
383 cliOptions,
384 defaultMode,
385 forcedAddOns,
386 { disableNameCheck: true },
387 )
388 launchUI({
389 mode: 'setup',
390 options: {
391 ...createSerializedOptions(optionsFromCLI!),
392 projectName: 'my-app',
393 targetDir: resolve(process.cwd(), 'my-app'),
394 },
395 forcedRouterMode: defaultMode,
396 forcedAddOns,
397 environmentFactory: () => createUIEnvironment(appName, false),
398 webBase,
399 })
400 return
401 }
402​
403 if (finalOptions) {
404 intro(`Creating a new ${appName} app in ${projectName}...`)
405 } else {
406 intro(`Let's configure your ${appName} application`)
407 finalOptions = await promptForCreateOptions(cliOptions, {
408 forcedMode: defaultMode,
409 forcedAddOns,
410 })
411 }
412​
413 if (!finalOptions) {
414 throw new Error('No options were provided')
415 }
416​
417 finalOptions.targetDir =
418 options.targetDir || resolve(process.cwd(), finalOptions.projectName)
419​
420 await createApp(environment, finalOptions)
421 } catch (error) {
422 log.error(
423 error instanceof Error ? error.message : 'An unknown error occurred',
424 )
425 process.exit(1)
426 }
427 }
428 })
429​
430 program.parse()