@hzab/vite-config 0.0.2-alpha.0 → 0.0.3-alpha.1

package/src/create-app-vite-config.ts

@@ -1,218 +1,236 @@
-import basicSsl from "@vitejs/plugin-basic-ssl";
-import react from "@vitejs/plugin-react";
-import { mergeConfig, type PluginOption, type UserConfig } from "vite";
-import { createHtmlPlugin } from "vite-plugin-html";
-
-import { copyPlugin } from "./plugins/copy.ts";
-import { createHashBuildDirName, hashDeployPlugin } from "./plugins/hash-deploy.ts";
-import { buildLessOptions } from "./plugins/less-tilde.ts";
-import { lifecyclePlugin } from "./plugins/lifecycle.ts";
-import { publicAssetsPlugin } from "./plugins/public-assets.ts";
-import { publicConfigPlugin } from "./plugins/public-config.ts";
-import { reactCompilerPlugin } from "./plugins/react-compiler.ts";
-import { svgReactPlugin } from "./plugins/svg-react.ts";
-
-import type { CreateAppViteConfigOptions, CreateAppViteConfigResult } from "./types.ts";
-
-/** 根入口运行时资源前缀，供 JS `fetch` / 动态 URL 使用。与 HTML 子目录 `PUBLIC_PATH` 可能不同。 */
-const JS_PUBLIC_PATH_DEFINE_KEY = "import.meta.env.PUBLIC_PATH";
-
-/** 规范化资源 base：空串视为未设置；非空则保证尾 `/`。 */
-function normalizeAssetBase(base: string | undefined): string | undefined {
-  if (base == null) return undefined;
-  const trimmed = base.trim();
-  if (!trimmed) return undefined;
-  return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
-}
-
-function ensureTrailingSlash(value: string): string {
-  return value.endsWith("/") ? value : `${value}/`;
-}
-
-/**
- * JS 可读的根入口前缀。相对 hash 必须用 `./{hash}/`，不能用 Vite `base`（后者保持 `./`）。
- * 非 hash 则跟最终 `config.base`；serve 未设 base 时为 `"/"`。
- */
-function resolveJsPublicPath(isHash: boolean, publicPath: string, config: UserConfig): string {
-  if (isHash) return publicPath;
-  if (typeof config.base === "string" && config.base.length > 0) {
-    return ensureTrailingSlash(config.base);
-  }
-  return publicPath || "/";
-}
-
-function applyJsPublicPathDefine(config: UserConfig, publicPath: string): UserConfig {
-  config.define = {
-    ...config.define,
-    [JS_PUBLIC_PATH_DEFINE_KEY]: JSON.stringify(publicPath),
-  };
-  return config;
-}
-
-/**
- * 组装应用侧 Vite 配置。
- *
- * 合并顺序：`base(options) → mergeConfig(base, vite) → configure(final)`，
- * 之后写入 `import.meta.env.PUBLIC_PATH`（同名 `define` 会被覆盖）。
- *
- * 返回值附带只读 `buildDirHash`（本次 hash 子目录名；未启用时为 `""`）。
- * @public
- */
-export function createAppViteConfig(
-  options: CreateAppViteConfigOptions,
-): CreateAppViteConfigResult {
-  const {
-    rootDir,
-    repositoryRoot,
-    command,
-    mode,
-    alias,
-    useHttps = false,
-    openBrowser = true,
-    hashDeploy = false,
-    hashTimestamp = "epoch",
-    base: baseOption,
-    deployRoot: deployRootOption = "dist",
-    hashCleanup,
-    publicAssets,
-    publicConfig,
-    copy: copyOption,
-    htmlData,
-    devProxy,
-    reactCompiler = "build-only",
-    react: enableReact = true,
-    svgr: svgrOption = false,
-    less,
-    onRun,
-    onDone,
-    plugins: extraPlugins = [],
-    vite: viteOverride,
-    configure,
-  } = options;
-
-  const isDev = command === "serve";
-  const isBuild = command === "build";
-  const isHash = isBuild && Boolean(hashDeploy) && mode !== "development";
-  const deployRoot = deployRootOption.replace(/\/+$/, "") || "dist";
-  const assetBase = normalizeAssetBase(baseOption);
-
-  const buildDirStr = isHash
-    ? createHashBuildDirName({
-        repositoryRoot: repositoryRoot ?? rootDir,
-        timestampFormat: hashTimestamp,
-      })
-    : "";
-  /**
-   * HTML / 根入口资源前缀（JS `import.meta.env.PUBLIC_PATH` 用这个）。
-   * - hash + 相对：`./{hash}/`（Vite `base` 仍为 `./`，由插件改写根入口）
-   * - hash + 绝对 base：`{base}{hash}/`（与 Vite `base` 一致）
-   * - 普通 build：`base` 或 `./`
-   */
-  const publicPath = isHash
-    ? `${assetBase ?? "./"}${buildDirStr}/`
-    : isBuild
-      ? (assetBase ?? "./")
-      : "";
-  /**
-   * Hash 子目录入口相对于自身加载资源；根入口由 hashDeployPlugin 再补 hash 前缀。
-   * 绝对 base 则两个入口都使用同一个完整 URL。
-   */
-  const htmlPublicPath = isHash && publicPath.startsWith("./") ? "./" : publicPath;
-  /** 相对 base（含默认 `./`）在 hash 下必须保持 Vite `base: "./"`，否则 `./{hash}/` 会被规范成 `/`。 */
-  const isAbsoluteAssetBase =
-    assetBase != null &&
-    (assetBase.startsWith("https://") ||
-      assetBase.startsWith("http://") ||
-      assetBase.startsWith("/"));
-  const viteBase = isHash
-    ? isAbsoluteAssetBase
-      ? publicPath
-      : "./"
-    : isBuild
-      ? publicPath
-      : undefined;
-  const enablePublicAssets = publicAssets !== false;
-
-  const plugins: PluginOption[] = [
-    ...(enablePublicAssets
-      ? [publicAssetsPlugin(publicAssets && typeof publicAssets === "object" ? publicAssets : {})]
-      : []),
-    ...(svgrOption ? [svgReactPlugin(svgrOption === true ? {} : svgrOption)] : []),
-    ...(enableReact ? [react()] : []),
-    ...reactCompilerPlugin({ command, mode: reactCompiler }),
-    ...(publicConfig === false || publicConfig == null
-      ? []
-      : [
-          publicConfigPlugin({
-            sourceGlob: publicConfig.sourceGlob ?? `config/public-config/${publicConfig.mode}/*`,
-            dest: publicConfig.dest,
-          }),
-        ]),
-    ...(copyOption ? [copyPlugin(copyOption)] : []),
-    createHtmlPlugin({
-      minify: isBuild,
-      inject: {
-        data: {
-          ...htmlData,
-          PUBLIC_PATH: htmlPublicPath || "",
-        },
-      },
-    }),
-    ...(isBuild && isHash
-      ? [
-          hashDeployPlugin({
-            rootDir,
-            buildDirStr,
-            publicPath,
-            cleanup: hashCleanup,
-          }),
-        ]
-      : []),
-    ...(isDev && useHttps ? [basicSsl()] : []),
-    ...extraPlugins,
-    ...(isBuild && (onRun || onDone) ? [lifecyclePlugin({ onRun, onDone })] : []),
-  ];
-
-  const base: UserConfig = {
-    root: rootDir,
-    ...(viteBase != null ? { base: viteBase } : {}),
-    plugins,
-    ...(enablePublicAssets ? { publicDir: false } : {}),
-    resolve: {
-      alias,
-    },
-    css: {
-      preprocessorOptions: {
-        less: buildLessOptions(less),
-      },
-    },
-    ...(isDev
-      ? {
-          server: {
-            https: useHttps ? {} : undefined,
-            host: true,
-            open: openBrowser,
-            ...(devProxy ? { proxy: devProxy } : {}),
-          },
-        }
-      : {
-          build: {
-            outDir: isHash ? `${deployRoot}/${buildDirStr}/` : deployRoot,
-            assetsDir: "assets",
-            emptyOutDir: true,
-          },
-        }),
-  };
-
-  let merged = viteOverride ? mergeConfig(base, viteOverride) : base;
-  if (configure) {
-    merged = configure(merged);
-  }
-  applyJsPublicPathDefine(merged, resolveJsPublicPath(isHash, publicPath, merged));
-  Object.defineProperty(merged, "buildDirHash", {
-    value: buildDirStr,
-    enumerable: false,
-    configurable: true,
-  });
-  return merged as CreateAppViteConfigResult;
-}
+import basicSsl from "@vitejs/plugin-basic-ssl";
+import react from "@vitejs/plugin-react";
+import { mergeConfig, type PluginOption, type UserConfig } from "vite";
+import { createHtmlPlugin } from "vite-plugin-html";
+
+import { copyPlugin } from "./plugins/copy.ts";
+import { DEFAULT_HASH_DIR_NAME_PATTERN } from "./plugins/hash-dir-name.ts";
+import { createHashBuildDirName, hashDeployPlugin } from "./plugins/hash-deploy.ts";
+import { buildLessOptions } from "./plugins/less-tilde.ts";
+import { lifecyclePlugin } from "./plugins/lifecycle.ts";
+import { publicAssetsPlugin } from "./plugins/public-assets.ts";
+import { publicConfigPlugin } from "./plugins/public-config.ts";
+import { reactCompilerPlugin } from "./plugins/react-compiler.ts";
+import { svgReactPlugin } from "./plugins/svg-react.ts";
+
+import type { CreateAppViteConfigOptions, CreateAppViteConfigResult } from "./types.ts";
+
+/** 根入口运行时资源前缀，供 JS `fetch` / 动态 URL 使用。与 HTML 子目录 `PUBLIC_PATH` 可能不同。 */
+const JS_PUBLIC_PATH_DEFINE_KEY = "import.meta.env.PUBLIC_PATH";
+
+/** 规范化资源 base：空串视为未设置；非空则保证尾 `/`。 */
+function normalizeAssetBase(base: string | undefined): string | undefined {
+  if (base == null) return undefined;
+  const trimmed = base.trim();
+  if (!trimmed) return undefined;
+  return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
+}
+
+function ensureTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+/**
+ * JS 可读的根入口前缀。相对 hash 必须用 `./{hash}/`，不能用 Vite `base`（后者保持 `./`）。
+ * 非 hash 则跟最终 `config.base`；serve 未设 base 时为 `"/"`。
+ */
+function resolveJsPublicPath(isHash: boolean, publicPath: string, config: UserConfig): string {
+  if (isHash) return publicPath;
+  if (typeof config.base === "string" && config.base.length > 0) {
+    return ensureTrailingSlash(config.base);
+  }
+  return publicPath || "/";
+}
+
+function applyJsPublicPathDefine(config: UserConfig, publicPath: string): UserConfig {
+  config.define = {
+    ...config.define,
+    [JS_PUBLIC_PATH_DEFINE_KEY]: JSON.stringify(publicPath),
+  };
+  return config;
+}
+
+/**
+ * 组装应用侧 Vite 配置。
+ *
+ * 合并顺序：`base(options) → mergeConfig(base, vite) → configure(final)`，
+ * 之后写入 `import.meta.env.PUBLIC_PATH`（同名 `define` 会被覆盖）。
+ *
+ * 返回值附带只读 `buildDirHash`（本次 hash 子目录名；未启用时为 `""`）。
+ * @public
+ */
+export function createAppViteConfig(
+  options: CreateAppViteConfigOptions,
+): CreateAppViteConfigResult {
+  const {
+    rootDir,
+    repositoryRoot,
+    command,
+    mode,
+    alias,
+    useHttps = false,
+    openBrowser = true,
+    hashDeploy = false,
+    hashDirName,
+    base: baseOption,
+    deployRoot: deployRootOption = "dist",
+    hashCleanup,
+    publicAssets,
+    publicConfig,
+    copy: copyOption,
+    htmlData,
+    devProxy,
+    reactCompiler = "build-only",
+    react: enableReact = true,
+    svgr: svgrOption = false,
+    less,
+    onRun,
+    onDone,
+    plugins: extraPlugins = [],
+    vite: viteOverride,
+    configure,
+  } = options;
+
+  const isDev = command === "serve";
+  const isBuild = command === "build";
+  const isHash = isBuild && Boolean(hashDeploy) && mode !== "development";
+  const deployRoot = deployRootOption.replace(/\/+$/, "") || "dist";
+  const assetBase = normalizeAssetBase(baseOption);
+
+  // hashTimestamp 已移除：只有 "datetime" 会改变目录名，出现即报错并给出等价模式串写法；
+  // 与默认等价的 "epoch" 忽略即可。避免部署目录名被静默改变。
+  const legacyHashTimestamp = (options as { hashTimestamp?: unknown }).hashTimestamp;
+  if (legacyHashTimestamp != null && legacyHashTimestamp !== "epoch") {
+    throw new Error(
+      `[vite-config] hashTimestamp: ${JSON.stringify(
+        legacyHashTimestamp,
+      )} has been removed; use hashDirName instead (e.g. "hash-timestamp" or "hash-YYYY-MM-DD-HH-mm-ss").`,
+    );
+  }
+
+  const buildDirStr = isHash
+    ? createHashBuildDirName({
+        repositoryRoot: repositoryRoot ?? rootDir,
+        hashDirName,
+      })
+    : "";
+  /**
+   * 生效的目录名模式串：透传给 hashDeployPlugin，让 cleanup 只识别同一模式串生成的目录。
+   * `hashDirName` 不传时即默认模式串。
+   */
+  const buildDirNamePattern = hashDirName ?? DEFAULT_HASH_DIR_NAME_PATTERN;
+  /**
+   * HTML / 根入口资源前缀（JS `import.meta.env.PUBLIC_PATH` 用这个）。
+   * - hash + 相对：`./{hash}/`（Vite `base` 仍为 `./`，由插件改写根入口）
+   * - hash + 绝对 base：`{base}{hash}/`（与 Vite `base` 一致）
+   * - 普通 build：`base` 或 `./`
+   */
+  const publicPath = isHash
+    ? `${assetBase ?? "./"}${buildDirStr}/`
+    : isBuild
+      ? (assetBase ?? "./")
+      : "";
+  /**
+   * Hash 子目录入口相对于自身加载资源；根入口由 hashDeployPlugin 再补 hash 前缀。
+   * 绝对 base 则两个入口都使用同一个完整 URL。
+   */
+  const htmlPublicPath = isHash && publicPath.startsWith("./") ? "./" : publicPath;
+  /** 相对 base（含默认 `./`）在 hash 下必须保持 Vite `base: "./"`，否则 `./{hash}/` 会被规范成 `/`。 */
+  const isAbsoluteAssetBase =
+    assetBase != null &&
+    (assetBase.startsWith("https://") ||
+      assetBase.startsWith("http://") ||
+      assetBase.startsWith("/"));
+  const viteBase = isHash
+    ? isAbsoluteAssetBase
+      ? publicPath
+      : "./"
+    : isBuild
+      ? publicPath
+      : undefined;
+  const enablePublicAssets = publicAssets !== false;
+
+  const plugins: PluginOption[] = [
+    ...(enablePublicAssets
+      ? [publicAssetsPlugin(publicAssets && typeof publicAssets === "object" ? publicAssets : {})]
+      : []),
+    ...(svgrOption ? [svgReactPlugin(svgrOption === true ? {} : svgrOption)] : []),
+    ...(enableReact ? [react()] : []),
+    ...reactCompilerPlugin({ command, mode: reactCompiler }),
+    ...(publicConfig === false || publicConfig == null
+      ? []
+      : [
+          publicConfigPlugin({
+            sourceGlob: publicConfig.sourceGlob ?? `config/public-config/${publicConfig.mode}/*`,
+            dest: publicConfig.dest,
+          }),
+        ]),
+    ...(copyOption ? [copyPlugin(copyOption)] : []),
+    createHtmlPlugin({
+      minify: isBuild,
+      inject: {
+        data: {
+          ...htmlData,
+          PUBLIC_PATH: htmlPublicPath || "",
+        },
+      },
+    }),
+    ...(isBuild && isHash
+      ? [
+          hashDeployPlugin({
+            rootDir,
+            buildDirStr,
+            buildDirNamePattern,
+            publicPath,
+            cleanup: hashCleanup,
+          }),
+        ]
+      : []),
+    ...(isDev && useHttps ? [basicSsl()] : []),
+    ...extraPlugins,
+    ...(isBuild && (onRun || onDone) ? [lifecyclePlugin({ onRun, onDone })] : []),
+  ];
+
+  const base: UserConfig = {
+    root: rootDir,
+    ...(viteBase != null ? { base: viteBase } : {}),
+    plugins,
+    ...(enablePublicAssets ? { publicDir: false } : {}),
+    resolve: {
+      alias,
+    },
+    css: {
+      preprocessorOptions: {
+        less: buildLessOptions(less),
+      },
+    },
+    ...(isDev
+      ? {
+          server: {
+            https: useHttps ? {} : undefined,
+            host: true,
+            open: openBrowser,
+            ...(devProxy ? { proxy: devProxy } : {}),
+          },
+        }
+      : {
+          build: {
+            outDir: isHash ? `${deployRoot}/${buildDirStr}/` : deployRoot,
+            assetsDir: "assets",
+            emptyOutDir: true,
+          },
+        }),
+  };
+
+  let merged = viteOverride ? mergeConfig(base, viteOverride) : base;
+  if (configure) {
+    merged = configure(merged);
+  }
+  applyJsPublicPathDefine(merged, resolveJsPublicPath(isHash, publicPath, merged));
+  Object.defineProperty(merged, "buildDirHash", {
+    value: buildDirStr,
+    enumerable: false,
+    configurable: true,
+  });
+  return merged as CreateAppViteConfigResult;
+}