@hzab/vite-config 0.0.2-alpha.0

package/src/plugins/hash-deploy.ts

@@ -0,0 +1,199 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import type { PluginOption } from "vite";
+
+/** @public */
+export type HashTimestampFormat = "epoch" | "datetime";
+
+/** @public */
+export interface HashBuildDirNameOptions {
+  repositoryRoot?: string;
+  now?: number;
+  /** @defaultValue "epoch" */
+  timestampFormat?: HashTimestampFormat;
+}
+
+/** @public */
+export interface HashCleanupOptions {
+  /**
+   * 每次成功构建后保留的 Hash 版本总数（含本次构建）。
+   * 必须为大于等于 1 的整数。
+   */
+  keep: number;
+}
+
+/** @public */
+export interface HashDeployPluginOptions {
+  rootDir: string;
+  /** hash 子目录名，如 `{commit}-{timestamp}` 或 `{commit}-YYYY-MM-DD-HH-mm-ss` */
+  buildDirStr: string;
+  /**
+   * 与最终 Vite `base` 一致的资源前缀。
+   * - 默认相对：`./{buildDirStr}/`
+   * - 自定义 CDN：`https://cdn.example.com/app/{buildDirStr}/`
+   */
+  publicPath: string;
+  /** 旧 Hash 目录清理策略；未传时永久保留，由部署系统负责清理。 */
+  cleanup?: HashCleanupOptions;
+}
+
+const HASH_BUILD_DIR_PATTERN = /^(?:[0-9a-f]{12}|local)-(\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}|\d+)$/;
+
+function parseHashTimestamp(value: string): number {
+  if (/^\d+$/.test(value)) return Number(value);
+  const [year = 0, month = 1, day = 1, hour = 0, minute = 0, second = 0] = value
+    .split("-")
+    .map(Number);
+  return new Date(year, month - 1, day, hour, minute, second).getTime();
+}
+
+function padTwo(value: number): string {
+  return String(value).padStart(2, "0");
+}
+
+function formatHashTimestamp(now: number, format: HashTimestampFormat = "epoch"): string {
+  if (format !== "datetime") return String(now);
+  const date = new Date(now);
+  return [
+    date.getFullYear(),
+    padTwo(date.getMonth() + 1),
+    padTwo(date.getDate()),
+    padTwo(date.getHours()),
+    padTwo(date.getMinutes()),
+    padTwo(date.getSeconds()),
+  ].join("-");
+}
+
+function cleanupOldHashBuilds(deployRoot: string, currentBuildDir: string, keep: number): void {
+  const oldBuilds = fs
+    .readdirSync(deployRoot, { withFileTypes: true })
+    .flatMap((entry) => {
+      if (!entry.isDirectory() || entry.name === currentBuildDir) return [];
+      const match = HASH_BUILD_DIR_PATTERN.exec(entry.name);
+      return match ? [{ name: entry.name, timestamp: parseHashTimestamp(match[1]!) }] : [];
+    })
+    .sort((left, right) => right.timestamp - left.timestamp || right.name.localeCompare(left.name));
+
+  for (const build of oldBuilds.slice(Math.max(keep - 1, 0))) {
+    fs.rmSync(path.join(deployRoot, build.name), { recursive: true });
+  }
+}
+
+/**
+ * 构建结束后写 `dist/hash.txt`，并把 hash 子目录中的 `index.html` 复制到 `dist/index.html`。
+ * 相对 `base` 时为根入口补上 hash 前缀；绝对 `base` 时产物已含完整 URL，原样复制即可。
+ * 配置 `cleanup.keep` 时，成功写入根入口后只保留指定数量的最新 Hash 版本。
+ * @public
+ */
+export function hashDeployPlugin(options: HashDeployPluginOptions): PluginOption {
+  const { rootDir, buildDirStr, publicPath, cleanup } = options;
+  if (cleanup && (!Number.isInteger(cleanup.keep) || cleanup.keep < 1)) {
+    throw new Error("[hash-deploy] cleanup.keep must be an integer greater than or equal to 1.");
+  }
+  let outputDir: string | undefined;
+  let deployRoot: string | undefined;
+
+  return {
+    name: "hash-deploy",
+    enforce: "post",
+    configResolved(config) {
+      const resolvedRoot = path.resolve(config.root);
+      const expectedRoot = path.resolve(rootDir);
+      if (resolvedRoot !== expectedRoot) {
+        throw new Error(
+          `[hash-deploy] Vite root "${resolvedRoot}" must match rootDir "${expectedRoot}".`,
+        );
+      }
+      // 相对 hash：工厂 publicPath 为 `./{hash}/`，但 Vite base 必须保持 `./`。
+      const expectedBase = publicPath.startsWith("./") ? "./" : publicPath;
+      if (config.base !== expectedBase) {
+        throw new Error(
+          `[hash-deploy] Vite base "${config.base}" must remain "${expectedBase}" during hash deployment.`,
+        );
+      }
+
+      outputDir = path.resolve(resolvedRoot, config.build.outDir);
+      if (path.basename(outputDir) !== buildDirStr) {
+        throw new Error(
+          `[hash-deploy] build.outDir "${config.build.outDir}" must end with the hash directory "${buildDirStr}".`,
+        );
+      }
+      deployRoot = path.dirname(outputDir);
+    },
+    writeBundle: {
+      sequential: true,
+      order: "post",
+      handler() {
+        if (!outputDir || !deployRoot) {
+          throw new Error("[hash-deploy] Vite configuration was not resolved before writeBundle.");
+        }
+
+        const sourceIndex = path.join(outputDir, "index.html");
+        if (!fs.existsSync(sourceIndex)) {
+          throw new Error(`[hash-deploy] Generated entry was not found: "${sourceIndex}".`);
+        }
+
+        fs.mkdirSync(deployRoot, { recursive: true });
+        fs.writeFileSync(path.join(deployRoot, "hash.txt"), buildDirStr);
+        const sourceHtml = fs.readFileSync(sourceIndex, "utf8");
+        // 相对 base（`./{hash}/`）时子目录 HTML 中的资源均相对于自身，根入口需统一补 hash；
+        // 绝对 base 时 Vite 已写出完整 URL，直接复制。
+        const rootHtml = publicPath.startsWith("./")
+          ? sourceHtml.replace(/(\b(?:href|src)\s*=\s*["'])\.\//g, `$1${publicPath}`)
+          : sourceHtml;
+        fs.writeFileSync(path.join(deployRoot, "index.html"), rootHtml);
+        if (cleanup) {
+          cleanupOldHashBuilds(deployRoot, buildDirStr, cleanup.keep);
+        }
+      },
+    },
+  };
+}
+
+/**
+ * 从指定仓库读取短 commit hash；非 git 环境回退 `local`。
+ * @public
+ */
+export function getCommitHash(repositoryRoot: string = process.cwd()): string {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: repositoryRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .trim()
+      .slice(0, 12);
+  } catch {
+    return "local";
+  }
+}
+
+/**
+ * 生成 hash 构建目录名；保留仅传时间戳的旧调用方式。
+ * @public
+ */
+export function createHashBuildDirName(now?: number): string;
+/** @public */
+export function createHashBuildDirName(repositoryRoot: string, now?: number): string;
+/** @public */
+export function createHashBuildDirName(options: HashBuildDirNameOptions): string;
+export function createHashBuildDirName(
+  repositoryRootOrNowOrOptions?: string | number | HashBuildDirNameOptions,
+  now: number = Date.now(),
+): string {
+  if (repositoryRootOrNowOrOptions != null && typeof repositoryRootOrNowOrOptions === "object") {
+    const {
+      repositoryRoot,
+      now: optionsNow = Date.now(),
+      timestampFormat = "epoch",
+    } = repositoryRootOrNowOrOptions;
+    return `${getCommitHash(repositoryRoot)}-${formatHashTimestamp(optionsNow, timestampFormat)}`;
+  }
+  const repositoryRoot =
+    typeof repositoryRootOrNowOrOptions === "string" ? repositoryRootOrNowOrOptions : undefined;
+  const timestamp =
+    typeof repositoryRootOrNowOrOptions === "number" ? repositoryRootOrNowOrOptions : now;
+  return `${getCommitHash(repositoryRoot)}-${formatHashTimestamp(timestamp)}`;
+}

package/src/plugins/less-tilde.ts

@@ -0,0 +1,44 @@
+import type { LessOptions } from "../types.ts";
+
+/**
+ * Less 插件：把 webpack 遗留的 `~pkg/...` 导入解析到 node_modules。
+ *
+ * Less 自身不认识 `~`（那是 webpack `less-loader` 的约定：从 node_modules 解析）；Vite 的
+ * Less 预处理器也不处理 `~`，会回退到 Less 默认 FileManager 去查找 `node_modules/~pkg/...` 而失败。
+ * 本插件注册一个 FileManager：仅当导入以 `~` 开头时拦截，去掉前缀后交给默认 FileManager 解析
+ * （Vite 恒向 `less.render` 注入 `paths: ["node_modules"]`）。
+ *
+ * 第三方包（如 formily 系）自带 `@import "~antd/..."` 时尤其需要——消费方无法修改 node_modules。
+ * @public
+ */
+export function lessTildeResolutionPlugin() {
+  return {
+    install(less: any, pluginManager: any) {
+      class TildeFileManager extends less.FileManager {
+        supports(filename: string) {
+          return filename.startsWith("~");
+        }
+        loadFile(filename: string, currentDirectory: string, options: any, environment: any) {
+          // `~pkg/...` → `pkg/...`，让默认 FileManager 从 node_modules 解析
+          return super.loadFile(filename.slice(1), currentDirectory, options, environment);
+        }
+      }
+      pluginManager.addFileManager(new TildeFileManager());
+    },
+  };
+}
+
+/**
+ * 组装 `css.preprocessorOptions.less`：映射 webpack `less-loader` 选项，
+ * `less.resolveTilde: true` 时注入 `~` 解析插件（默认关闭）。
+ * @public
+ */
+export function buildLessOptions(less?: LessOptions) {
+  const resolveTilde = less?.resolveTilde === true;
+  return {
+    ...(less?.additionalData != null ? { additionalData: less.additionalData } : {}),
+    ...(less?.modifyVars != null ? { modifyVars: less.modifyVars } : {}),
+    ...(less?.javascriptEnabled != null ? { javascriptEnabled: less.javascriptEnabled } : {}),
+    ...(resolveTilde ? { plugins: [lessTildeResolutionPlugin()] } : {}),
+  };
+}

package/src/plugins/lifecycle.ts

@@ -0,0 +1,40 @@
+import type { PluginOption } from "vite";
+
+/** @public */
+export interface LifecyclePluginOptions {
+  /** 构建开始（Vite `buildStart`）。仅同步。 */
+  onRun?: () => void;
+  /**
+   * 产物写盘成功之后（`writeBundle` sequential post）。
+   * 工厂中排在 Hash 根入口写入之后；Hash 写入失败不会调用。
+   */
+  onDone?: () => void | Promise<void>;
+}
+
+/**
+ * 构建起止回调。`onDone` 使用 sequential post `writeBundle`，
+ * 以便排在 Hash 部署等其它 post 写入之后。
+ * @public
+ */
+export function lifecyclePlugin(options: LifecyclePluginOptions = {}): PluginOption {
+  const { onRun, onDone } = options;
+
+  return {
+    name: "build-lifecycle",
+    enforce: "post",
+    buildStart() {
+      if (typeof onRun === "function") {
+        onRun();
+      }
+    },
+    writeBundle: {
+      sequential: true,
+      order: "post",
+      async handler() {
+        if (typeof onDone === "function") {
+          await onDone();
+        }
+      },
+    },
+  };
+}

package/src/plugins/public-assets.ts

@@ -0,0 +1,28 @@
+import { copyPlugin } from "./copy.ts";
+
+import type { PluginOption } from "vite";
+
+/** @public */
+export interface PublicAssetsPluginOptions {
+  /**
+   * 源目录，相对项目 root。
+   * @defaultValue "public"
+   */
+  dir?: string;
+}
+
+/**
+ * 将 `public/**` 复制到产物 `public/` 子目录（保留目录结构），替代 Vite 默认 publicDir 根目录散落。
+ * @public
+ */
+export function publicAssetsPlugin(options: PublicAssetsPluginOptions = {}): PluginOption {
+  const { dir = "public" } = options;
+  return copyPlugin({
+    targets: [
+      {
+        src: `${dir}/**/*`,
+        dest: ".",
+      },
+    ],
+  });
+}

package/src/plugins/public-config.ts

@@ -0,0 +1,34 @@
+import { copyPlugin } from "./copy.ts";
+
+import type { PluginOption } from "vite";
+
+/** @public */
+export interface PublicConfigPluginOptions {
+  /** 源 glob，如 `config/public-config/development/*` */
+  sourceGlob: string;
+  /**
+   * 产物目标目录（可由消费方覆盖）。
+   * @defaultValue "config"（站点根 `/config/`）
+   * @example "public/config"
+   */
+  dest?: string;
+}
+
+/**
+ * 将运行时 public-config 复制到产物目录（默认 `config/`，配合 `window.globalConfig`）。
+ * @public
+ */
+export function publicConfigPlugin(options: PublicConfigPluginOptions): PluginOption {
+  const { sourceGlob, dest = "config" } = options;
+  return copyPlugin({
+    targets: [
+      {
+        src: sourceGlob,
+        dest,
+        rename: {
+          stripBase: true,
+        },
+      },
+    ],
+  });
+}

package/src/plugins/react-compiler.ts

@@ -0,0 +1,32 @@
+import babel from "@rolldown/plugin-babel";
+import { reactCompilerPreset } from "@vitejs/plugin-react";
+
+import type { ReactCompilerMode } from "../types.ts";
+import type { PluginOption } from "vite";
+
+/** @public */
+export interface ReactCompilerPluginOptions {
+  command: string;
+  /**
+   * - `true`：始终启用
+   * - `"build-only"`：仅 build，且 `REACT_COMPILER=false` 可关
+   * - `false`：关闭
+   */
+  mode?: ReactCompilerMode;
+}
+
+/**
+ * React Compiler（babel preset）。默认仅生产构建启用。
+ * @public
+ */
+export function reactCompilerPlugin(options: ReactCompilerPluginOptions): PluginOption[] {
+  const { command, mode = "build-only" } = options;
+  if (mode === false) return [];
+
+  const isBuild = command === "build";
+  const enabled = mode === true ? true : isBuild && process.env.REACT_COMPILER !== "false";
+
+  if (!enabled) return [];
+
+  return [babel({ presets: [reactCompilerPreset()] })];
+}

package/src/plugins/relative-base.ts

@@ -0,0 +1,20 @@
+import type { PluginOption } from "vite";
+
+/**
+ * hash 部署场景下，把资源路径与 `import.meta.env.BASE_URL` 改写成相对部署目录。
+ * @public
+ */
+export function relativeBasePlugin(deployPath: string = "./"): PluginOption {
+  return {
+    name: "relative-base",
+    transformIndexHtml(html: string) {
+      return html
+        .replace(/href="\.?\/assets\//g, `href="${deployPath}assets/`)
+        .replace(/src="\.?\/assets\//g, `src="${deployPath}assets/`);
+    },
+    transform(code: string, id: string) {
+      if (id.includes("node_modules")) return null;
+      return code.replace(/import\.meta\.env\.BASE_URL/g, `'${deployPath}'`);
+    },
+  };
+}

package/src/plugins/stub-less.ts

@@ -0,0 +1,26 @@
+import type { Plugin } from "vite";
+
+const cssModuleStub = `
+const styles = new Proxy({}, {
+  get: (_target, property) => typeof property === "string" ? property : undefined,
+});
+export default styles;
+`;
+
+/**
+ * 单测不解析 less，并为 CSS Modules 提供 identity stub
+ * @public
+ */
+export function stubLessPlugin(): Plugin {
+  return {
+    name: "stub-less",
+    load(id) {
+      if (/\.module\.less(?:$|\?)/.test(id)) {
+        return cssModuleStub;
+      }
+      if (/\.less(?:$|\?)/.test(id)) {
+        return "";
+      }
+    },
+  };
+}

package/src/plugins/svg-react.ts

@@ -0,0 +1,90 @@
+import fs from "node:fs/promises";
+import { transformWithOxc } from "vite";
+
+import type { Config } from "@svgr/core";
+import type { Plugin } from "vite";
+
+/**
+ * @see https://react-svgr.com/docs/options/
+ * @public
+ */
+export interface SvgReactOptions {
+  /** @defaultValue true */
+  svgo?: boolean;
+  icon?: boolean;
+  [key: string]: unknown;
+}
+
+const SVG_EXT_RE = /\.svg$/i;
+
+/**
+ * `*.svg?react`（及带其它 query 时的 `react` 段）。
+ * 不匹配 `?reactive` / webpack 的 `?svgEle`。
+ */
+export function isSvgReactId(id: string): boolean {
+  const queryStart = id.indexOf("?");
+  if (queryStart === -1) return false;
+  const file = id.slice(0, queryStart);
+  if (!SVG_EXT_RE.test(file)) return false;
+  return /(?:^|&)react(?:&|$)/.test(id.slice(queryStart + 1));
+}
+
+function missingPeerError(pkg: string, cause: unknown): Error {
+  const error = new Error(
+    `[svg-react] "${pkg}" is required to transform *.svg?react. Install the optional peer or disable CreateAppViteConfigOptions.svgr.`,
+  );
+  error.cause = cause;
+  return error;
+}
+
+async function resolveSvgrConfig(options: SvgReactOptions): Promise<Config> {
+  const merged: Config = { svgo: true, ...options };
+  if (merged.plugins != null) return merged;
+
+  const plugins: NonNullable<Config["plugins"]> = [];
+  if (merged.svgo !== false) {
+    try {
+      plugins.push((await import("@svgr/plugin-svgo")).default);
+    } catch (cause) {
+      throw missingPeerError("@svgr/plugin-svgo", cause);
+    }
+  }
+  try {
+    plugins.push((await import("@svgr/plugin-jsx")).default);
+  } catch (cause) {
+    throw missingPeerError("@svgr/plugin-jsx", cause);
+  }
+  return { ...merged, plugins };
+}
+
+/**
+ * 将 `import Icon from "./icon.svg?react"` 编成 React 组件。
+ * 普通 `*.svg` 仍走 Vite 默认资源 URL，本插件不处理。
+ *
+ * `@svgr/core` / `@svgr/plugin-jsx`（以及默认开启 SVGO 时的 `@svgr/plugin-svgo`）
+ * 仅在真正命中 `?react` 时动态加载，根入口不会静态依赖它们。
+ * @public
+ */
+export function svgReactPlugin(options: SvgReactOptions = {}): Plugin {
+  return {
+    name: "ccc:svg-react",
+    enforce: "pre",
+    async load(id) {
+      if (!isSvgReactId(id)) return;
+
+      const filePath = id.slice(0, id.indexOf("?"));
+      const svg = await fs.readFile(filePath, "utf8");
+      let transform;
+      try {
+        ({ transform } = await import("@svgr/core"));
+      } catch (cause) {
+        throw missingPeerError("@svgr/core", cause);
+      }
+      const componentCode = await transform(svg, await resolveSvgrConfig(options), { filePath });
+      const result = await transformWithOxc(componentCode, `${filePath}.jsx`, {
+        lang: "jsx",
+      });
+      return { code: result.code, map: result.map };
+    },
+  };
+}

package/src/svg-react-runtime.ts

@@ -0,0 +1,4 @@
+// Runtime counterpart of the `@hzab/vite-config/svg-react` types entry.
+// The ambient types for `*.svg?react` live in `src/svg-react.d.ts`; this module
+// intentionally exports nothing and exists only so the subpath resolves at runtime.
+export {};

package/src/svg-react.d.ts

@@ -0,0 +1,6 @@
+declare module "*.svg?react" {
+  import type { FunctionComponent, SVGProps } from "react";
+
+  const ReactComponent: FunctionComponent<SVGProps<SVGSVGElement>>;
+  export default ReactComponent;
+}