feat(cli): scaffold out astro add command

.changeset/brave-rings-jump.md

@@ -0,0 +1,9 @@
+---
+'astro': minor
+---
+
+Introduce new `astro add` command to automatically configure integrations.
+
+```shell
+npx astro add
+```

examples/with-tailwindcss/tailwind.config.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+	content: [],
+	theme: {
+		extend: {},
+	},
+	plugins: [],
+}

packages/astro/package.json

@@ -79,13 +79,17 @@
     "@astrojs/prism": "0.4.1-next.0",
     "@astrojs/webapi": "^0.11.0",
     "@babel/core": "^7.17.8",
+    "@babel/generator": "^7.17.7",
+    "@babel/parser": "^7.17.8",
     "@babel/traverse": "^7.17.3",
     "@proload/core": "^0.2.2",
     "@proload/plugin-tsm": "^0.1.1",
     "@web/parse5-utils": "^1.3.0",
+    "boxen": "^6.2.1",
     "ci-info": "^3.3.0",
     "common-ancestor-path": "^1.0.1",
     "debug": "^4.3.4",
+    "diff": "^5.0.0",
     "eol": "^0.9.1",
     "es-module-lexer": "^0.10.4",
     "esbuild": "0.14.25",
@@ -99,11 +103,14 @@
     "magic-string": "^0.25.9",
     "micromorph": "^0.1.2",
     "mime": "^3.0.0",
+    "ora": "^6.1.0",
     "parse5": "^6.0.1",
     "path-to-regexp": "^6.2.0",
     "postcss": "^8.4.12",
     "postcss-load-config": "^3.1.3",
+    "preferred-pm": "^3.0.3",
     "prismjs": "^1.27.0",
+    "prompts": "^2.4.2",
     "rehype-slug": "^5.0.1",
     "resolve": "^1.22.0",
     "rollup": "^2.70.1",
@@ -126,16 +133,19 @@
   "devDependencies": {
     "@babel/types": "^7.17.0",
     "@types/babel__core": "^7.1.19",
+    "@types/babel__generator": "^7.6.4",
     "@types/babel__traverse": "^7.14.2",
     "@types/chai": "^4.3.0",
     "@types/common-ancestor-path": "^1.0.0",
     "@types/connect": "^3.4.35",
     "@types/debug": "^4.1.7",
+    "@types/diff": "^5.0.2",
     "@types/estree": "^0.0.51",
     "@types/html-escaper": "^3.0.0",
     "@types/mime": "^2.0.3",
     "@types/mocha": "^9.1.0",
     "@types/parse5": "^6.0.3",
+    "@types/prettier": "^2.4.4",
     "@types/resolve": "^1.20.1",
     "@types/rimraf": "^3.0.2",
     "@types/send": "^0.17.1",

packages/astro/src/cli/index.ts

@@ -8,36 +8,31 @@ import yargs from 'yargs-parser';
 import { z } from 'zod';
 import { defaultLogDestination } from '../core/logger.js';
 import build from '../core/build/index.js';
+import add from '../core/add/index.js';
 import devServer from '../core/dev/index.js';
 import preview from '../core/preview/index.js';
 import { check } from './check.js';
 import { formatConfigError, loadConfig } from '../core/config.js';
-import { pad } from '../core/dev/util.js';
+import { printHelp } from '../core/messages.js';
 
 type Arguments = yargs.Arguments;
-type CLICommand = 'help' | 'version' | 'dev' | 'build' | 'preview' | 'reload' | 'check';
+type CLICommand = 'help' | 'version' | 'add' | 'dev' | 'build' | 'preview' | 'reload' | 'check';
 
 /** Display --help flag */
-function printHelp() {
-	linebreak();
-	headline('astro', 'Futuristic web development tool.');
-	linebreak();
-	title('Commands');
-	table(
-		[
+function printAstroHelp() {
+	printHelp({
+		commandName: 'astro',
+		headline: 'Futuristic web development tool.',
+		commands: [
+			['add', 'Add an integration to your configuration.'],
 			['dev', 'Run Astro in development mode.'],
 			['build', 'Build a pre-compiled production-ready site.'],
 			['preview', 'Preview your build locally before deploying.'],
 			['check', 'Check your project for errors.'],
 			['--version', 'Show the version number and exit.'],
 			['--help', 'Show this help message.'],
 		],
-		{ padding: 28, prefix: '  astro ' }
-	);
-	linebreak();
-	title('Flags');
-	table(
-		[
+		flags: [
 			['--host [optional IP]', 'Expose server on network'],
 			['--config <path>', 'Specify the path to the Astro config file.'],
 			['--project-root <path>', 'Specify the path to the project root folder.'],
@@ -48,39 +43,7 @@ function printHelp() {
 			['--verbose', 'Enable verbose logging'],
 			['--silent', 'Disable logging'],
 		],
-		{ padding: 28, prefix: '  ' }
-	);
-
-	// Logging utils
-	function linebreak() {
-		console.log();
-	}
-
-	function headline(name: string, tagline: string) {
-		console.log(`  ${colors.bgGreen(colors.black(` ${name} `))} ${colors.green(`v${process.env.PACKAGE_VERSION ?? ''}`)} ${tagline}`);
-	}
-	function title(label: string) {
-		console.log(`  ${colors.bgWhite(colors.black(` ${label} `))}`);
-	}
-	function table(rows: [string, string][], opts: { padding: number; prefix: string }) {
-		const split = rows.some((row) => {
-			const message = `${opts.prefix}${' '.repeat(opts.padding)}${row[1]}`;
-			return message.length > process.stdout.columns;
-		});
-		for (const row of rows) {
-			row.forEach((col, i) => {
-				if (i === 0) {
-					process.stdout.write(`${opts.prefix}${colors.bold(pad(`${col}`, opts.padding - opts.prefix.length))}`);
-				} else {
-					if (split) {
-						process.stdout.write('\n    ');
-					}
-					process.stdout.write(colors.dim(col) + '\n');
-				}
-			});
-		}
-		return '';
-	}
+	});
 }
 
 /** Display --version flag */
@@ -93,15 +56,15 @@ async function printVersion() {
 
 /** Determine which command the user requested */
 function resolveCommand(flags: Arguments): CLICommand {
-	if (flags.version) {
-		return 'version';
-	} else if (flags.help) {
-		return 'help';
-	}
 	const cmd = flags._[2] as string;
+	if (cmd === 'add') return 'add';
+
+	if (flags.version) return 'version';
+	else if (flags.help) return 'help';
+
 	const supportedCommands = new Set(['dev', 'build', 'preview', 'check']);
 	if (supportedCommands.has(cmd)) {
-		return cmd as 'dev' | 'build' | 'preview' | 'check';
+		return cmd as CLICommand;
 	}
 	return 'help';
 }
@@ -110,11 +73,11 @@ function resolveCommand(flags: Arguments): CLICommand {
 export async function cli(args: string[]) {
 	const flags = yargs(args);
 	const cmd = resolveCommand(flags);
-	const projectRoot = flags.projectRoot || flags._[3];
+	const projectRoot = flags.projectRoot;
 
 	switch (cmd) {
 		case 'help':
-			printHelp();
+			printAstroHelp();
 			return process.exit(0);
 		case 'version':
 			await printVersion();
@@ -135,13 +98,25 @@ export async function cli(args: string[]) {
 
 	let config: AstroConfig;
 	try {
+		// Note: ideally, `loadConfig` would return the config AND its filePath
+		// For now, `add` has to resolve the config again internally
 		config = await loadConfig({ cwd: projectRoot, flags });
 	} catch (err) {
 		throwAndExit(err);
 		return;
 	}
 
 	switch (cmd) {
+		case 'add': {
+				try {
+					const packages = flags._.slice(3) as string[];
+					await add(packages, { cwd: projectRoot, flags, logging });
+					process.exit(0);
+				} catch (err) {
+					throwAndExit(err);
+				}
+				return;
+		}
 		case 'dev': {
 			try {
 				await devServer(config, { logging });
@@ -150,7 +125,6 @@ export async function cli(args: string[]) {
 			} catch (err) {
 				throwAndExit(err);
 			}
-
 			return;
 		}
 

packages/astro/src/core/add/babel.ts

@@ -0,0 +1,17 @@
+import traverse from '@babel/traverse';
+import generator from '@babel/generator';
+import * as t from '@babel/types';
+import parser from '@babel/parser';
+
+// @ts-ignore @babel/traverse isn't ESM and needs this trick
+export const visit = traverse.default as typeof traverse;
+export { t };
+
+export async function generate(ast: t.File) {
+	// @ts-ignore @babel/generator isn't ESM and needs this trick
+	const astToText = generator.default as typeof generator;
+	const { code } = astToText(ast);
+	return code;
+}
+
+export const parse = (code: string) => parser.parse(code, { sourceType: 'unambiguous', plugins: ['typescript'] });

packages/astro/src/core/add/consts.ts

@@ -0,0 +1,26 @@
+export const FIRST_PARTY_FRAMEWORKS = [
+	{ value: 'react', title: 'React' },
+	{ value: 'preact', title: 'Preact' },
+	{ value: 'vue', title: 'Vue' },
+	{ value: 'svelte', title: 'Svelte' },
+	{ value: 'solid-js', title: 'Solid' },
+	{ value: 'lit', title: 'Lit' },
+];
+export const FIRST_PARTY_ADDONS = [
+	{ value: 'tailwind', title: 'Tailwind' },
+	{ value: 'turbolinks', title: 'Turbolinks' },
+	{ value: 'partytown', title: 'Partytown' },
+	{ value: 'sitemap', title: 'Sitemap' },
+];
+export const ALIASES = new Map([
+	['solid', 'solid-js'],
+	['tailwindcss', 'tailwind'],
+]);
+export const CONFIG_STUB = `import { defineConfig } from 'astro/config';\n\nexport default defineConfig({});`;
+export const TAILWIND_CONFIG_STUB = `module.exports = {
+	content: [],
+	theme: {
+		extend: {},
+	},
+	plugins: [],
+}\n`;

packages/astro/src/core/add/imports.ts

@@ -0,0 +1,35 @@
+import { t, visit } from './babel.js';
+
+export function ensureImport(root: t.File, importDeclaration: t.ImportDeclaration) {
+	let specifiersToFind = [...importDeclaration.specifiers];
+
+	visit(root, {
+		ImportDeclaration(path) {
+			if (path.node.source.value === importDeclaration.source.value) {
+				path.node.specifiers.forEach((specifier) =>
+					specifiersToFind.forEach((specifierToFind, i) => {
+						if (specifier.type !== specifierToFind.type) return;
+						if (specifier.local.name === specifierToFind.local.name) {
+							specifiersToFind.splice(i, 1);
+						}
+					})
+				);
+			}
+		},
+	});
+
+	if (specifiersToFind.length === 0) return;
+
+	visit(root, {
+		Program(path) {
+			const declaration = t.importDeclaration(specifiersToFind, importDeclaration.source);
+			const latestImport = path
+				.get('body')
+				.filter((statement) => statement.isImportDeclaration())
+				.pop();
+
+			if (latestImport) latestImport.insertAfter(declaration);
+			else path.unshiftContainer('body', declaration);
+		},
+	});
+}