@hzab/vite-config 0.0.2-alpha.0

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

@@ -0,0 +1,218 @@
+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;
+}

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

@@ -0,0 +1,199 @@
+import path from "node:path";
+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 { lifecyclePlugin } from "./plugins/lifecycle.ts";
+import { buildLessOptions } from "./plugins/less-tilde.ts";
+import { reactCompilerPlugin } from "./plugins/react-compiler.ts";
+import { svgReactPlugin } from "./plugins/svg-react.ts";
+
+import type { CreateLibraryViteConfigOptions, LibraryFormats } from "./types.ts";
+
+/**
+ * 组件库构建默认外置
+ * 传入 `externals` 时整表替换；追加时展开本常量。
+ * @public
+ */
+export const DEFAULT_LIBRARY_EXTERNALS = ["react", "react-dom"] as const;
+
+/**
+ * UMD / IIFE 默认全局名。未出现在表里的字符串 external 用自身包名。
+ * @public
+ */
+export const DEFAULT_LIBRARY_GLOBALS: Record<string, string> = {
+  react: "React",
+  "react-dom": "ReactDOM",
+};
+
+const DEFAULT_LIBRARY_FORMATS: LibraryFormats[] = ["umd"];
+
+function needsLibraryName(formats: readonly LibraryFormats[]): boolean {
+  return formats.includes("umd") || formats.includes("iife");
+}
+
+function resolveExternals(
+  externals: CreateLibraryViteConfigOptions["externals"],
+): (string | RegExp)[] {
+  if (externals === false) return [];
+  if (externals == null) return [...DEFAULT_LIBRARY_EXTERNALS];
+  return externals;
+}
+
+function resolveLibraryFileName(
+  fileName: CreateLibraryViteConfigOptions["fileName"],
+  formats: readonly LibraryFormats[],
+): string | ((format: string, entryName: string) => string) {
+  if (fileName != null) return fileName;
+  if (formats.length === 1) {
+    return () => "index.js";
+  }
+  return (format) => (format === "es" ? "index.js" : `index.${format}.js`);
+}
+
+function resolveLibraryGlobals(
+  externals: readonly (string | RegExp)[],
+  globals?: Record<string, string>,
+): Record<string, string> {
+  const inferred: Record<string, string> = {};
+  for (const ext of externals) {
+    if (typeof ext !== "string") continue;
+    inferred[ext] = DEFAULT_LIBRARY_GLOBALS[ext] ?? ext;
+  }
+  return { ...inferred, ...globals };
+}
+
+/** 字符串 external 同时匹配子路径（如 `react` → `react/jsx-runtime`）。 */
+export function matchLibraryExternal(id: string, externals: readonly (string | RegExp)[]): boolean {
+  const source = id.split("?")[0] ?? id;
+  return externals.some((ext) => {
+    if (typeof ext === "string") {
+      return source === ext || source.startsWith(`${ext}/`);
+    }
+    return ext.test(source);
+  });
+}
+
+function resolveLibraryGlobalName(id: string, globals: Record<string, string>): string {
+  const source = id.split("?")[0] ?? id;
+  if (globals[source]) return globals[source];
+  const matched = Object.keys(globals).find(
+    (key) => source === key || source.startsWith(`${key}/`),
+  );
+  return matched ? (globals[matched] ?? source) : source;
+}
+
+/**
+ * 组装组件库 Vite 配置：build 走 `build.lib`（默认 UMD → `lib/`），serve 为预览应用。
+ *
+ * 不启用 Hash 部署、public 复制、public-config。不默认 `example/` 预览目录或 antd / Formily externals。
+ *
+ * 合并顺序：`base(options) → mergeConfig(base, vite) → configure(final)`
+ * @public
+ */
+export function createLibraryViteConfig(options: CreateLibraryViteConfigOptions): UserConfig {
+  const {
+    rootDir,
+    command,
+    alias,
+    entry = "src/index.ts",
+    name,
+    outDir = "lib",
+    fileName,
+    cssFileName = "index",
+    formats = DEFAULT_LIBRARY_FORMATS,
+    externals: externalsOption,
+    globals: globalsOption,
+    useHttps = false,
+    openBrowser = true,
+    devProxy,
+    reactCompiler = "build-only",
+    react: enableReact = true,
+    svgr: svgrOption = false,
+    less,
+    previewHtml,
+    onRun,
+    onDone,
+    plugins: extraPlugins = [],
+    vite: viteOverride,
+    configure,
+  } = options;
+
+  const isDev = command === "serve";
+  const isBuild = command === "build";
+
+  if (isBuild && needsLibraryName(formats) && (name == null || name.trim() === "")) {
+    throw new Error(
+      '[vite-config] createLibraryViteConfig: `name` is required when formats include "umd" or "iife".',
+    );
+  }
+
+  const plugins: PluginOption[] = [
+    ...(svgrOption ? [svgReactPlugin(svgrOption === true ? {} : svgrOption)] : []),
+    ...(enableReact ? [react()] : []),
+    ...reactCompilerPlugin({ command, mode: reactCompiler }),
+    ...(isDev && previewHtml
+      ? [
+          createHtmlPlugin({
+            minify: false,
+            template: path.resolve(rootDir, previewHtml),
+          }),
+        ]
+      : []),
+    ...(isDev && useHttps ? [basicSsl()] : []),
+    ...extraPlugins,
+    ...(isBuild && (onRun || onDone) ? [lifecyclePlugin({ onRun, onDone })] : []),
+  ];
+
+  const resolvedExternals = resolveExternals(externalsOption);
+  const resolvedGlobals = resolveLibraryGlobals(resolvedExternals, globalsOption);
+
+  const base: UserConfig = {
+    root: rootDir,
+    publicDir: false,
+    plugins,
+    resolve: {
+      alias,
+    },
+    css: {
+      preprocessorOptions: {
+        less: buildLessOptions(less),
+      },
+    },
+    ...(isDev
+      ? {
+          server: {
+            https: useHttps ? {} : undefined,
+            host: true,
+            open: openBrowser,
+            ...(devProxy ? { proxy: devProxy } : {}),
+          },
+        }
+      : {
+          build: {
+            outDir,
+            emptyOutDir: true,
+            lib: {
+              entry: path.resolve(rootDir, entry),
+              ...(name != null && name.trim() !== "" ? { name } : {}),
+              formats,
+              fileName: resolveLibraryFileName(fileName, formats),
+              cssFileName,
+            },
+            rolldownOptions: {
+              external: (id: string) => matchLibraryExternal(id, resolvedExternals),
+              output: {
+                globals: (id: string) => resolveLibraryGlobalName(id, resolvedGlobals),
+              },
+            },
+          },
+        }),
+  };
+
+  let merged = viteOverride ? mergeConfig(base, viteOverride) : base;
+  if (configure) {
+    merged = configure(merged);
+  }
+  return merged;
+}

package/src/create-package-vitest-config.ts

@@ -0,0 +1,54 @@
+import react from "@vitejs/plugin-react";
+import { mergeConfig, type PluginOption } from "vite";
+
+import { stubLessPlugin } from "./plugins/stub-less.ts";
+
+import type { CreatePackageVitestConfigOptions } from "./vitest-types.ts";
+import type { ViteUserConfig as VitestUserConfig } from "vitest/config";
+
+/**
+ * 组装包级 Vitest 配置。
+ *
+ * 合并顺序：`base(options) → mergeConfig(base, vite) → configure(final)`
+ */
+export function createPackageVitestConfig(
+  options: CreatePackageVitestConfigOptions,
+): VitestUserConfig {
+  const {
+    packageRoot,
+    alias,
+    react: enableReact = false,
+    stubLess = false,
+    environment = "happy-dom",
+    include = ["test/**/*.test.ts"],
+    setupFiles,
+    plugins: extraPlugins = [],
+    vite: viteOverride,
+    configure,
+  } = options;
+
+  const plugins: PluginOption[] = [
+    ...(enableReact ? [react()] : []),
+    ...(stubLess ? [stubLessPlugin()] : []),
+    ...extraPlugins,
+  ];
+
+  const base: VitestUserConfig = {
+    root: packageRoot,
+    plugins,
+    resolve: {
+      alias,
+    },
+    test: {
+      environment,
+      include,
+      ...(setupFiles ? { setupFiles } : {}),
+    },
+  };
+
+  let merged = viteOverride ? mergeConfig(base, viteOverride) : base;
+  if (configure) {
+    merged = configure(merged);
+  }
+  return merged;
+}

package/src/create-vite-config.ts

@@ -0,0 +1,22 @@
+import { createAppViteConfig } from "./create-app-vite-config.ts";
+
+import type { CreateAppViteConfigOptions, CreateAppViteConfigResult } from "./types.ts";
+
+/** @public */
+export type CreateViteConfigOptions = Partial<CreateAppViteConfigOptions>;
+
+/**
+ * Default Vite factory for consumer apps.
+ * Existing `createAppViteConfig` remains the full-control API.
+ * @public
+ */
+export function createViteConfig(options: CreateViteConfigOptions = {}): CreateAppViteConfigResult {
+  return createAppViteConfig({
+    rootDir: options.rootDir ?? process.cwd(),
+    command: options.command ?? "serve",
+    mode: options.mode ?? "development",
+    openBrowser: options.openBrowser ?? false,
+    reactCompiler: false,
+    ...options,
+  });
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+export { createAppViteConfig } from "./create-app-vite-config.ts";
+export { createViteConfig } from "./create-vite-config.ts";
+export type { CreateViteConfigOptions } from "./create-vite-config.ts";
+export {
+  createLibraryViteConfig,
+  DEFAULT_LIBRARY_EXTERNALS,
+  DEFAULT_LIBRARY_GLOBALS,
+} from "./create-library-vite-config.ts";
+export { copyPlugin } from "./plugins/copy.ts";
+export type {
+  HashBuildDirNameOptions,
+  HashCleanupOptions,
+  HashDeployPluginOptions,
+  HashTimestampFormat,
+} from "./plugins/hash-deploy.ts";
+export { createHashBuildDirName, getCommitHash, hashDeployPlugin } from "./plugins/hash-deploy.ts";
+export type { LifecyclePluginOptions } from "./plugins/lifecycle.ts";
+export { lifecyclePlugin } from "./plugins/lifecycle.ts";
+export { buildLessOptions, lessTildeResolutionPlugin } from "./plugins/less-tilde.ts";
+export type { PublicAssetsPluginOptions } from "./plugins/public-assets.ts";
+export { publicAssetsPlugin } from "./plugins/public-assets.ts";
+export type { PublicConfigPluginOptions } from "./plugins/public-config.ts";
+export { publicConfigPlugin } from "./plugins/public-config.ts";
+export type { ReactCompilerPluginOptions } from "./plugins/react-compiler.ts";
+export { reactCompilerPlugin } from "./plugins/react-compiler.ts";
+export { relativeBasePlugin } from "./plugins/relative-base.ts";
+export { stubLessPlugin } from "./plugins/stub-less.ts";
+export { svgReactPlugin } from "./plugins/svg-react.ts";
+export type {
+  CopyOption,
+  CopyPluginOptions,
+  CopyTarget,
+  CreateAppViteConfigOptions,
+  CreateAppViteConfigResult,
+  CreateLibraryViteConfigOptions,
+  LessOptions,
+  LibraryFormats,
+  PublicAssetsOptions,
+  PublicConfigOptions,
+  ReactCompilerMode,
+  SvgReactOptions,
+} from "./types.ts";

package/src/plugins/copy.ts

@@ -0,0 +1,25 @@
+import { viteStaticCopy } from "vite-plugin-static-copy";
+
+import type { PluginOption } from "vite";
+import type { Target, ViteStaticCopyOptions } from "vite-plugin-static-copy";
+
+/** @public */
+export type CopyTarget = Target;
+/** @public */
+export type CopyPluginOptions = ViteStaticCopyOptions;
+
+/** @public */
+export type CopyOption = CopyPluginOptions | CopyTarget[];
+
+export function resolveCopyPluginOptions(options: CopyOption): CopyPluginOptions {
+  return Array.isArray(options) ? { targets: options } : options;
+}
+
+/**
+ * 通用静态复制，封装 `vite-plugin-static-copy`。
+ * 可传完整选项，或直接传 `targets` 数组。
+ * @public
+ */
+export function copyPlugin(options: CopyOption): PluginOption {
+  return viteStaticCopy(resolveCopyPluginOptions(options));
+}