create-analog 3.0.0-alpha.6 → 3.0.0-alpha.61

package/index.js

@@ -3,17 +3,73 @@
 // @ts-check
 import { blue, green, red, reset, yellow } from 'kolorist';
 import minimist from 'minimist';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import prompts from 'prompts';
 
+/**
+ * @typedef {'latest' | 'blog' | 'minimal'} Template
+ * @typedef {'prismjs' | 'shiki'} HighlighterId
+ * @typedef {(value: string) => string} Colorizer
+ *
+ * @typedef {object} Variant
+ * @property {string} name
+ * @property {Template} template
+ * @property {Colorizer} color
+ *
+ * @typedef {object} AppDefinition
+ * @property {string} name
+ * @property {Colorizer} color
+ * @property {readonly Variant[]} variants
+ *
+ * @typedef {object} HighlighterConfig
+ * @property {string} highlighter
+ * @property {string} entryPoint
+ * @property {Record<string, string>} dependencies
+ *
+ * @typedef {object} PackageJson
+ * @property {string} [name]
+ * @property {Record<string, string>} [scripts]
+ * @property {Record<string, string>} [dependencies]
+ * @property {Record<string, string>} [devDependencies]
+ *
+ * @typedef {object} PromptAnswers
+ * @property {string} [projectName]
+ * @property {boolean} [overwrite]
+ * @property {string} [packageName]
+ * @property {Template} [variant]
+ * @property {boolean} [tailwind]
+ * @property {HighlighterId} [syntaxHighlighter]
+ *
+ * @typedef {object} UserAgentPackage
+ * @property {string} name
+ * @property {string} version
+ *
+ * @typedef {{
+ *   _: string[];
+ *   template?: string;
+ *   t?: string;
+ *   skipTailwind?: boolean | string;
+ *   skipGit?: boolean | string;
+ * } & Record<string, unknown>} CliArgv
+ */
+
+const CLI_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_TARGET_DIR = 'analog-project';
+const DEFAULT_BLOG_HIGHLIGHTER = 'prismjs';
+
+/** @type {readonly Template[]} */
+const H3_TEMPLATES = ['latest', 'blog', 'minimal'];
+
 // Avoids autoconversion to number of the project name by defining that the args
 // non associated with an option ( _ ) needs to be parsed as a string. See #4606
+/** @type {CliArgv} */
 const argv = minimist(process.argv.slice(2), { string: ['_'] });
 const cwd = process.cwd();
 
+/** @type {readonly AppDefinition[]} */
 const APPS = [
   {
     name: 'Analog',
@@ -37,6 +93,8 @@ const APPS = [
     ],
   },
 ];
+
+/** @type {Readonly<Record<HighlighterId, HighlighterConfig>>} */
 const HIGHLIGHTERS = {
   prismjs: {
     highlighter: 'withPrismHighlighter',
@@ -50,118 +108,139 @@ const HIGHLIGHTERS = {
     highlighter: 'withShikiHighlighter',
     entryPoint: 'shiki-highlighter',
     dependencies: {
-      marked: '^15.0.7',
+      marked: '^18.0.0',
       'marked-shiki': '^1.1.0',
       shiki: '^1.6.1',
     },
   },
 };
 
+/** @type {Readonly<Record<string, string>>} */
 const renameFiles = {
   _gitignore: '.gitignore',
 };
 
+const TAILWIND_POSTCSS_CONFIG = `export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+`;
+
 async function init() {
   let targetDir = formatTargetDir(argv._[0]);
-  let template = argv.template || argv.t;
+  let template = resolveTemplate(argv.template ?? argv.t);
   let skipTailwind = fromBoolArg(argv.skipTailwind);
+  const skipGit = fromBoolArg(argv.skipGit ?? argv['skip-git']) ?? false;
+
+  // Internal flag (no prompt): when set, strip the `overrides` block that
+  // pins vite/vitest from the generated package.json. Defaults to keeping
+  // them, preserving current behavior.
+  const skipViteOverrides = fromBoolArg(argv.skipViteOverrides);
 
-  const defaultTargetDir = 'analog-project';
   const getProjectName = () =>
-    targetDir === '.' ? path.basename(path.resolve()) : targetDir;
+    targetDir === '.' ? path.basename(path.resolve()) : (targetDir ?? '');
 
+  /** @type {PromptAnswers} */
   let result = {};
 
   try {
-    result = await prompts(
-      [
-        {
-          type: targetDir ? null : 'text',
-          name: 'projectName',
-          message: reset('Project name:'),
-          initial: defaultTargetDir,
-          onState: (state) => {
-            targetDir = formatTargetDir(state.value) || defaultTargetDir;
+    result = /** @type {PromptAnswers} */ (
+      await prompts(
+        [
+          {
+            type: targetDir ? null : 'text',
+            name: 'projectName',
+            message: reset('Project name:'),
+            initial: DEFAULT_TARGET_DIR,
+            onState: (state) => {
+              targetDir =
+                formatTargetDir(String(state.value ?? '')) ||
+                DEFAULT_TARGET_DIR;
+            },
           },
-        },
-        {
-          type: () =>
-            !fs.existsSync(targetDir) || isEmpty(targetDir) ? null : 'confirm',
-          name: 'overwrite',
-          message: () =>
-            (targetDir === '.'
-              ? 'Current directory'
-              : `Target directory "${targetDir}"`) +
-            ` is not empty. Remove existing files and continue?`,
-        },
-        {
-          type: (_, { overwrite } = {}) => {
-            if (overwrite === false) {
-              throw new Error(red('✖') + ' Operation cancelled');
-            }
-            return null;
+          {
+            type: () =>
+              !targetDir || !fs.existsSync(targetDir) || isEmpty(targetDir)
+                ? null
+                : 'confirm',
+            name: 'overwrite',
+            message: () =>
+              (targetDir === '.'
+                ? 'Current directory'
+                : `Target directory "${targetDir}"`) +
+              ' is not empty. Remove existing files and continue?',
           },
-          name: 'overwriteChecker',
-        },
-        {
-          type: () => (isValidPackageName(getProjectName()) ? null : 'text'),
-          name: 'packageName',
-          message: reset('Package name:'),
-          initial: () => toValidPackageName(getProjectName()),
-          validate: (dir) =>
-            isValidPackageName(dir) || 'Invalid package.json name',
-        },
-        {
-          type: template ? null : 'select',
-          name: 'variant',
-          message: reset('What would you like to start?:'),
-          // @ts-ignore
-          choices: APPS[0].variants.map((variant) => {
-            const variantColor = variant.color;
-            return {
-              title: variantColor(variant.name),
+          {
+            type: (_, promptState = {}) => {
+              if (promptState.overwrite === false) {
+                throw new Error(`${red('✖')} Operation cancelled`);
+              }
+              return null;
+            },
+            name: 'overwriteChecker',
+          },
+          {
+            type: () => (isValidPackageName(getProjectName()) ? null : 'text'),
+            name: 'packageName',
+            message: reset('Package name:'),
+            initial: () => toValidPackageName(getProjectName()),
+            validate: (dir) =>
+              isValidPackageName(String(dir)) || 'Invalid package.json name',
+          },
+          {
+            type: template ? null : 'select',
+            name: 'variant',
+            message: reset('What would you like to start?:'),
+            choices: APPS[0].variants.map((variant) => ({
+              title: variant.color(variant.name),
               value: variant.template,
-            };
-          }),
-        },
-        {
-          type: (prev) => (prev === 'blog' ? 'select' : null),
-          name: 'syntaxHighlighter',
-          message: reset('Choose a syntax highlighter:'),
-          choices: Object.keys(HIGHLIGHTERS).map((highlighter) => ({
-            title: highlighter,
-            value: highlighter,
-          })),
-          initial: 1,
-        },
+            })),
+          },
+          {
+            type: (prev) => (prev === 'blog' ? 'select' : null),
+            name: 'syntaxHighlighter',
+            message: reset('Choose a syntax highlighter:'),
+            choices:
+              /** @type {{ title: HighlighterId; value: HighlighterId }[]} */ (
+                Object.keys(HIGHLIGHTERS).map((highlighter) => ({
+                  title: /** @type {HighlighterId} */ (highlighter),
+                  value: /** @type {HighlighterId} */ (highlighter),
+                }))
+              ),
+            initial: 1,
+          },
+          {
+            type: skipTailwind === undefined ? 'confirm' : null,
+            name: 'tailwind',
+            message: 'Would you like to add Tailwind to your project?',
+          },
+        ],
         {
-          type: skipTailwind === undefined ? 'confirm' : null,
-          name: 'tailwind',
-          message: 'Would you like to add Tailwind to your project?',
-        },
-      ],
-      {
-        onCancel: () => {
-          throw new Error(red('✖') + ' Operation cancelled');
+          onCancel: () => {
+            throw new Error(`${red('✖')} Operation cancelled`);
+          },
         },
-      },
+      )
     );
-  } catch (cancelled) {
-    console.log(cancelled.message);
+  } catch (error) {
+    console.log(error instanceof Error ? error.message : String(error));
     return;
   }
 
-  // user choice associated with prompts
-  const {
-    framework,
-    overwrite,
-    packageName,
-    variant,
-    tailwind,
-    syntaxHighlighter,
-  } = result;
+  const { overwrite, packageName, variant, tailwind, syntaxHighlighter } =
+    result;
+
+  template = variant ?? template;
+  if (!template) {
+    throw new Error('A project template must be selected.');
+  }
+
+  const highlighter =
+    syntaxHighlighter ??
+    (template === 'blog' ? DEFAULT_BLOG_HIGHLIGHTER : undefined);
 
-  const root = path.join(cwd, targetDir);
+  const root = path.join(cwd, targetDir ?? DEFAULT_TARGET_DIR);
 
   if (overwrite) {
     emptyDir(root);
@@ -169,58 +248,58 @@ async function init() {
     fs.mkdirSync(root, { recursive: true });
   }
 
-  // determine template
-  template = variant || framework || template;
-  // determine syntax highlighter
-  const highlighter =
-    syntaxHighlighter ?? (template === 'blog' ? 'prism' : null);
   skipTailwind = skipTailwind ?? !tailwind;
 
   console.log(`\nScaffolding project in ${root}...`);
 
-  const templateDir = path.resolve(
-    fileURLToPath(import.meta.url),
-    '..',
-    `template-${template}`,
-  );
-
-  const filesDir = path.resolve(fileURLToPath(import.meta.url), '..', `files`);
+  const templateDir = path.resolve(CLI_DIR, `template-${template}`);
+  const filesDir = path.resolve(CLI_DIR, 'files');
 
+  /**
+   * @param {string} file
+   * @param {string | undefined} [content]
+   */
   const write = (file, content) => {
     const targetPath = renameFiles[file]
       ? path.join(root, renameFiles[file])
       : path.join(root, file);
 
-    if (content) {
+    if (typeof content === 'string') {
       fs.writeFileSync(targetPath, content);
-    } else {
-      copy(path.join(templateDir, file), targetPath);
+      return;
     }
+
+    copy(path.join(templateDir, file), targetPath);
   };
 
   const files = fs.readdirSync(templateDir);
-  for (const file of files.filter((f) => f !== 'package.json')) {
+  for (const file of files.filter((entry) => entry !== 'package.json')) {
     write(file);
   }
 
   if (!skipTailwind) {
     addTailwindDirectives(write, filesDir);
+    write('postcss.config.mjs', TAILWIND_POSTCSS_CONFIG);
   }
 
   replacePlaceholders(root, 'vite.config.ts', {
     __TAILWIND_IMPORT__: !skipTailwind
-      ? `\nimport tailwindcss from '@tailwindcss/vite';`
+      ? "import tailwindcss from '@tailwindcss/vite';\n"
       : '',
-    __TAILWIND_PLUGIN__: !skipTailwind ? '\n    tailwindcss()' : '',
+    __TAILWIND_PLUGIN__: !skipTailwind ? '    tailwindcss(),\n' : '',
   });
 
-  const pkgInfo = pkgFromUserAgent(process.env.npm_config_user_agent);
-  const pkgManager = pkgInfo ? pkgInfo.name : 'npm';
+  /** @type {PackageJson} */
   const pkg = JSON.parse(
-    fs.readFileSync(path.join(templateDir, `package.json`), 'utf-8'),
+    fs.readFileSync(path.join(templateDir, 'package.json'), 'utf-8'),
   );
+  const pkgManager =
+    pkgFromUserAgent(process.env.npm_config_user_agent)?.name ?? 'npm';
 
   pkg.name = packageName || getProjectName();
+  pkg.scripts ??= {};
+  pkg.dependencies ??= {};
+  pkg.devDependencies ??= {};
   pkg.scripts.start = getStartCommand(pkgManager);
 
   if (template === 'blog' && highlighter) {
@@ -239,6 +318,14 @@ async function init() {
     addPnpmDependencies(pkg, template);
   }
 
+  if (skipViteOverrides && pkg.overrides) {
+    delete pkg.overrides.vite;
+    delete pkg.overrides.vitest;
+    if (Object.keys(pkg.overrides).length === 0) {
+      delete pkg.overrides;
+    }
+  }
+
   pkg.dependencies = sortObjectKeys(pkg.dependencies);
   pkg.devDependencies = sortObjectKeys(pkg.devDependencies);
 
@@ -246,18 +333,22 @@ async function init() {
 
   setProjectTitle(root, getProjectName());
 
-  console.log(`\nInitializing git repository:`);
-  execSync(`git init ${targetDir} && cd ${targetDir} && git add .`);
-
-  // Fail Silent
-  // Can fail when user does not have global git credentials
-  try {
-    execSync(`cd ${targetDir} && git commit -m "initial commit"`);
-  } catch {
-    /* ignore */
+  if (!skipGit) {
+    console.log('\nInitializing git repository:');
+    execFileSync('git', ['init', targetDir], { stdio: 'inherit' });
+    execFileSync('git', ['-C', targetDir, 'add', '.'], { stdio: 'inherit' });
+
+    // Can fail when the user does not have global git credentials.
+    try {
+      execFileSync('git', ['-C', targetDir, 'commit', '-m', 'initial commit'], {
+        stdio: 'inherit',
+      });
+    } catch {
+      /* ignore */
+    }
   }
 
-  console.log(`\nDone. Now run:\n`);
+  console.log('\nDone. Now run:\n');
   if (root !== cwd) {
     console.log(`  cd ${path.relative(cwd, root)}`);
   }
@@ -268,22 +359,30 @@ async function init() {
 
 /**
  * @param {string | undefined} targetDir
+ * @returns {string | undefined}
  */
 function formatTargetDir(targetDir) {
   return targetDir?.trim().replace(/\/+$/g, '');
 }
 
+/**
+ * @param {string} src
+ * @param {string} dest
+ * @returns {void}
+ */
 function copy(src, dest) {
   const stat = fs.statSync(src);
   if (stat.isDirectory()) {
     copyDir(src, dest);
-  } else {
-    fs.copyFileSync(src, dest);
+    return;
   }
+
+  fs.copyFileSync(src, dest);
 }
 
 /**
  * @param {string} projectName
+ * @returns {boolean}
  */
 function isValidPackageName(projectName) {
   return /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(
@@ -293,6 +392,7 @@ function isValidPackageName(projectName) {
 
 /**
  * @param {string} projectName
+ * @returns {string}
  */
 function toValidPackageName(projectName) {
   return projectName
@@ -306,6 +406,7 @@ function toValidPackageName(projectName) {
 /**
  * @param {string} srcDir
  * @param {string} destDir
+ * @returns {void}
  */
 function copyDir(srcDir, destDir) {
   fs.mkdirSync(destDir, { recursive: true });
@@ -317,42 +418,49 @@ function copyDir(srcDir, destDir) {
 }
 
 /**
- * @param {string} path
+ * @param {string} directoryPath
+ * @returns {boolean}
  */
-function isEmpty(path) {
-  const files = fs.readdirSync(path);
+function isEmpty(directoryPath) {
+  const files = fs.readdirSync(directoryPath);
   return files.length === 0 || (files.length === 1 && files[0] === '.git');
 }
 
 /**
  * @param {string} dir
+ * @returns {void}
  */
 function emptyDir(dir) {
   if (!fs.existsSync(dir)) {
     return;
   }
+
   for (const file of fs.readdirSync(dir)) {
     fs.rmSync(path.resolve(dir, file), { recursive: true, force: true });
   }
 }
 
 /**
- * @param {string | undefined} userAgent process.env.npm_config_user_agent
- * @returns object | undefined
+ * @param {string | undefined} userAgent
+ * @returns {UserAgentPackage | undefined}
  */
 function pkgFromUserAgent(userAgent) {
-  if (!userAgent) return undefined;
+  if (!userAgent) {
+    return undefined;
+  }
+
   const pkgSpec = userAgent.split(' ')[0];
-  const pkgSpecArr = pkgSpec.split('/');
-  return {
-    name: pkgSpecArr[0],
-    version: pkgSpecArr[1],
-  };
+  const [name, version] = pkgSpec.split('/');
+  if (!name || !version) {
+    return undefined;
+  }
+
+  return { name, version };
 }
 
 /**
  * @param {string} pkgManager
- * @returns string
+ * @returns {string}
  */
 function getInstallCommand(pkgManager) {
   return pkgManager === 'yarn' ? 'yarn' : `${pkgManager} install`;
@@ -360,46 +468,83 @@ function getInstallCommand(pkgManager) {
 
 /**
  * @param {string} pkgManager
- * @returns string
+ * @returns {string}
  */
 function getStartCommand(pkgManager) {
   return pkgManager === 'yarn' ? 'yarn dev' : `${pkgManager} run dev`;
 }
 
+/**
+ * @param {(file: string, content?: string) => void} write
+ * @param {string} filesDir
+ * @returns {void}
+ */
 function addTailwindDirectives(write, filesDir) {
   write(
     'src/styles.css',
-    fs.readFileSync(path.join(filesDir, `styles.css`), 'utf-8'),
+    fs.readFileSync(path.join(filesDir, 'styles.css'), 'utf-8'),
   );
 }
 
+/**
+ * @param {PackageJson} pkg
+ * @returns {void}
+ */
 function addTailwindDependencies(pkg) {
-  pkg.dependencies['tailwindcss'] = '^4.1.4';
-  pkg.dependencies['postcss'] = '^8.5.3';
-  pkg.dependencies['@tailwindcss/vite'] = '^4.1.4';
+  pkg.devDependencies ??= {};
+  pkg.devDependencies.postcss = '^8.5.6';
+  pkg.devDependencies.tailwindcss = '^4.2.2';
+  pkg.devDependencies['@tailwindcss/postcss'] = '^4.2.2';
+  pkg.devDependencies['@tailwindcss/vite'] = '^4.2.2';
 }
 
+/**
+ * @param {PackageJson} pkg
+ * @param {Template} template
+ * @returns {void}
+ */
 function addYarnDevDependencies(pkg, template) {
-  // v18
-  if (template === 'latest' || template === 'blog' || template === 'minimal') {
-    pkg.devDependencies['h3'] = '^1.13.0';
+  if (H3_TEMPLATES.includes(template)) {
+    pkg.devDependencies ??= {};
+    pkg.devDependencies.h3 = '^1.13.0';
   }
 }
 
+/**
+ * @param {PackageJson} pkg
+ * @param {Template} template
+ * @returns {void}
+ */
 function addPnpmDependencies(pkg, template) {
-  if (template === 'latest' || template === 'blog' || template === 'minimal') {
-    pkg.dependencies['h3'] = '^1.13.0';
+  if (H3_TEMPLATES.includes(template)) {
+    pkg.dependencies ??= {};
+    pkg.dependencies.h3 = '^1.13.0';
+    pkg.dependencies.ofetch = '2.0.0-alpha.3';
+    // nitro is only imported via `nitro/vite` in vite.config.ts (a build-time
+    // tool). npm/yarn auto-hoist it as a transitive of @analogjs/platform;
+    // pnpm's strict node_modules layout doesn't, so add it explicitly for
+    // pnpm users only.
+    pkg.devDependencies ??= {};
+    pkg.devDependencies.nitro = '3.0.260522-beta';
   }
 }
 
+/**
+ * @param {string} root
+ * @param {PackageJson} pkg
+ * @param {HighlighterId} highlighter
+ * @returns {void}
+ */
 function ensureSyntaxHighlighter(root, pkg, highlighter) {
+  const config = HIGHLIGHTERS[highlighter];
+
   replacePlaceholders(root, 'src/app/app.config.ts', {
-    __HIGHLIGHTER__: HIGHLIGHTERS[highlighter].highlighter,
-    __HIGHLIGHTER_ENTRY_POINT__: HIGHLIGHTERS[highlighter].entryPoint,
+    __HIGHLIGHTER__: config.highlighter,
+    __HIGHLIGHTER_ENTRY_POINT__: config.entryPoint,
   });
 
-  const dependencies = HIGHLIGHTERS[highlighter].dependencies;
-  for (const [name, version] of Object.entries(dependencies)) {
+  pkg.dependencies ??= {};
+  for (const [name, version] of Object.entries(config.dependencies)) {
     pkg.dependencies[name] = version;
   }
 
@@ -408,44 +553,94 @@ function ensureSyntaxHighlighter(root, pkg, highlighter) {
   });
 }
 
+/**
+ * @param {Record<string, string>} obj
+ * @returns {Record<string, string>}
+ */
 function sortObjectKeys(obj) {
   return Object.keys(obj)
     .sort()
     .reduce((result, key) => {
       result[key] = obj[key];
       return result;
-    }, {});
+    }, /** @type {Record<string, string>} */ ({}));
 }
 
+/**
+ * @param {string} root
+ * @param {string} title
+ * @returns {void}
+ */
 function setProjectTitle(root, title) {
   replacePlaceholders(root, ['index.html', 'README.md'], {
     __PROJECT_TITLE__: title,
   });
 }
 
+/**
+ * @param {string} root
+ * @param {string | readonly string[]} files
+ * @param {Record<string, string>} config
+ * @returns {void}
+ */
 function replacePlaceholders(root, files, config) {
-  for (const file of toFlatArray(files)) {
+  for (const file of toArray(files)) {
     const filePath = path.join(root, file);
     const fileContent = fs.readFileSync(filePath, 'utf-8');
     const newFileContent = Object.keys(config).reduce(
       (content, placeholder) =>
-        content.replace(RegExp(placeholder, 'g'), config[placeholder]),
+        content.replaceAll(placeholder, config[placeholder]),
       fileContent,
     );
     fs.writeFileSync(filePath, newFileContent);
   }
 }
 
-function toFlatArray(value) {
-  return (Array.isArray(value) ? value : [value]).filter(Boolean).flat();
+/**
+ * @param {string | readonly string[] | undefined | null} value
+ * @returns {string[]}
+ */
+function toArray(value) {
+  if (value == null) {
+    return [];
+  }
+
+  return Array.isArray(value) ? [...value] : [/** @type {string} */ (value)];
 }
 
+/**
+ * @param {unknown} arg
+ * @returns {boolean | undefined}
+ */
 function fromBoolArg(arg) {
-  return ['boolean', 'undefined'].includes(typeof arg)
-    ? arg
-    : ['', 'true'].includes(arg);
+  if (typeof arg === 'boolean' || typeof arg === 'undefined') {
+    return arg;
+  }
+
+  if (typeof arg !== 'string') {
+    return undefined;
+  }
+
+  return arg === '' || arg === 'true';
+}
+
+/**
+ * @param {string | undefined} value
+ * @returns {Template | undefined}
+ */
+function resolveTemplate(value) {
+  return isTemplate(value) ? value : undefined;
+}
+
+/**
+ * @param {string | undefined} value
+ * @returns {value is Template}
+ */
+function isTemplate(value) {
+  return value === 'latest' || value === 'blog' || value === 'minimal';
 }
 
-init().catch((e) => {
-  console.error(e);
+init().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
 });