@hzab/vite-config 0.0.2-alpha.0

package/src/types.ts

@@ -0,0 +1,314 @@
+import type { CopyOption } from "./plugins/copy.ts";
+import type { HashCleanupOptions, HashTimestampFormat } from "./plugins/hash-deploy.ts";
+import type { SvgReactOptions } from "./plugins/svg-react.ts";
+import type { AliasOptions, PluginOption, ProxyOptions, UserConfig } from "vite";
+
+export type { CopyOption, CopyPluginOptions, CopyTarget } from "./plugins/copy.ts";
+export type { SvgReactOptions } from "./plugins/svg-react.ts";
+
+/**
+ * 对齐 Vite `build.lib.formats`。
+ * @public
+ */
+export type LibraryFormats = "es" | "cjs" | "umd" | "iife";
+
+/** @public */
+export type ReactCompilerMode = boolean | "build-only";
+
+/** @public */
+export interface PublicAssetsOptions {
+  /**
+   * 源目录，相对 rootDir。
+   * @defaultValue "public"
+   */
+  dir?: string;
+}
+
+/** @public */
+export interface PublicConfigOptions {
+  /** Vite mode，用于默认 sourceGlob */
+  mode: string;
+  /**
+   * 复制源 glob，相对项目 root。
+   * @defaultValue `config/public-config/${mode}/*`
+   */
+  sourceGlob?: string;
+  /**
+   * 产物内目标目录（可由消费方覆盖）。
+   * @defaultValue "config"（站点根）
+   * @example "public/config"
+   */
+  dest?: string;
+}
+
+/** @public */
+export interface LessOptions {
+  /** 等价 webpack less-loader `additionalData`；注入到每个 less 文件前 */
+  additionalData?: string | ((source: string, filename: string) => string);
+  /** 等价 `modifyVars` */
+  modifyVars?: Record<string, unknown>;
+  /** 常见于 antd less 主题；默认不设 */
+  javascriptEnabled?: boolean;
+  /**
+   * 是否解析 webpack 遗留的 `~pkg/...` 导入（从 node_modules）。
+   * - 默认 `false`（关闭，保持 Vite 默认行为与 worker 并行）
+   * - `true`：注入内置 `~` 解析插件，第三方包里的 `~antd/...` 也能编译
+   */
+  resolveTilde?: boolean;
+}
+
+/** @public */
+export interface CreateAppViteConfigOptions {
+  rootDir: string;
+  /**
+   * Git 仓库目录，用于生成 Hash 构建目录名。
+   * @defaultValue rootDir
+   */
+  repositoryRoot?: string;
+  command: "serve" | "build" | string;
+  mode: string;
+
+  /**
+   * 与 Vite `resolve.alias` 相同：
+   * - `Record<string, string>`
+   * - `{ find, replacement }[]`
+   */
+  alias?: AliasOptions;
+
+  useHttps?: boolean;
+  /**
+   * 开发服务器启动时是否自动打开浏览器（映射 `server.open`）。
+   * - `true`（默认）：打开站点根
+   * - `false`：不打开
+   * - `string`：作为 URL pathname 打开
+   * 也可经 `vite.server.open` / `configure` 覆盖。
+   */
+  openBrowser?: boolean | string;
+  /** 是否启用 hash 目录部署（且 mode !== development） */
+  hashDeploy?: boolean;
+  /**
+   * Hash 子目录名中的时间戳格式。
+   * - `"epoch"`（默认）：`{commit}-{Date.now()}`
+   * - `"datetime"`：`{commit}-YYYY-MM-DD-HH-mm-ss`（本地时区，零填充）
+   */
+  hashTimestamp?: HashTimestampFormat;
+  /**
+   * 构建资源公共路径（Vite `base`）。
+   * - 未传：build 默认 `"./"`（相对路径）
+   * - 可传绝对 HTTPS/HTTP 目录，如 `"https://cdn.example.com/app/"`
+   * - 启用 `hashDeploy` 时，实际 Vite `base` 为 `{base}{hash}/`（`base` 会自动补尾 `/`）
+   * 开发 `serve` 不由此字段设置（仍用 Vite 默认）。
+   */
+  base?: string;
+  /**
+   * 构建产物根目录。
+   * - 普通 build：即 `build.outDir`
+   * - hash 部署：为 `<deployRoot>/<hash>/` 的父目录，并在此写入 `index.html` / `hash.txt`
+   * @defaultValue "dist"
+   */
+  deployRoot?: string;
+  /**
+   * Hash 构建成功后的旧版本清理策略。
+   * 未传时保留所有版本，由部署系统负责清理。
+   */
+  hashCleanup?: HashCleanupOptions;
+  /**
+   * 静态资源目录复制策略。
+   * - 默认启用：复制到产物 `public/` 子目录，并关闭 Vite 内置 publicDir
+   * - `false`：恢复 Vite 默认 publicDir（文件落在 outDir 根目录）
+   */
+  publicAssets?: PublicAssetsOptions | false;
+  publicConfig?: PublicConfigOptions | false;
+  /**
+   * 额外静态复制。
+   * 可传 `vite-plugin-static-copy` 完整选项，或直接传 `targets` 数组。
+   * 独立用法见 `copyPlugin()`。
+   */
+  copy?: CopyOption;
+  /**
+   * 注入 HTML 模板的 EJS 数据，与内置 `PUBLIC_PATH` 合并。
+   * HTML `PUBLIC_PATH` 始终由工厂按 base / Hash 计算，消费方同名键会被覆盖。
+   * JS 请用 `import.meta.env.PUBLIC_PATH`（相对 Hash 为 `./{hash}/`），见 `@hzab/vite-config/client`。
+   */
+  htmlData?: Record<string, unknown>;
+  devProxy?: Record<string, ProxyOptions>;
+  /**
+   * React Compiler：
+   * - `true`：build 与 serve 都开
+   * - `"build-only"`（默认）：仅 build，且可用 `REACT_COMPILER=false` 关闭
+   * - `false`：关闭
+   */
+  reactCompiler?: ReactCompilerMode;
+  /**
+   * 是否启用 `@vitejs/plugin-react`。
+   * @defaultValue true
+   */
+  react?: boolean;
+  /**
+   * SVG React 组件通道（`import Icon from "./icon.svg?react"`）。
+   * - 未传 / `false`：关闭（默认）；普通 `*.svg` 仍走 Vite 资源 URL
+   * - `true`：启用，默认 `svgo: true`
+   * - 对象：启用并传入 SVGR 选项（如 `icon` / `svgo`）
+   *
+   * 真正转换时需安装可选 peer：`@svgr/core`、`@svgr/plugin-jsx`；
+   * 未关闭 `svgo` 时还需 `@svgr/plugin-svgo`。类型声明见 `@hzab/vite-config/svg-react`。
+   */
+  svgr?: boolean | SvgReactOptions;
+  /**
+   * Less 预处理器选项，映射到 `css.preprocessorOptions.less`
+   *（webpack `less-loader` 的 `additionalData` / `modifyVars` 等）。
+   */
+  less?: LessOptions;
+
+  /**
+   * 构建开始回调（Vite `buildStart`）。仅 `command === "build"` 时挂载。
+   */
+  onRun?: () => void;
+  /**
+   * 产物写盘成功后的回调（sequential post `writeBundle`）。
+   * 排在 Hash 根入口 / `hash.txt` 写入之后；写入失败不会调用。
+   * 仅 `command === "build"` 时挂载。
+   */
+  onDone?: () => void | Promise<void>;
+
+  /** 追加插件（排在内置插件之后、生命周期回调之前） */
+  plugins?: PluginOption[];
+  /** 经 mergeConfig 合并进最终配置 */
+  vite?: UserConfig;
+  /** 最终回调，可任意改 */
+  configure?: (config: UserConfig) => UserConfig;
+}
+
+/**
+ * `createAppViteConfig` 的返回值：Vite 配置 + 本次 hash 子目录名。
+ * `buildDirHash` 为非可枚举属性，展开进 `build()` / `defineConfig` 时不会污染配置。
+ * @public
+ */
+export type CreateAppViteConfigResult = UserConfig & {
+  /**
+   * 本次 hash 部署子目录名（`{commit}-{timestamp}`，或 `hashTimestamp: "datetime"` 时为
+   * `{commit}-YYYY-MM-DD-HH-mm-ss`）。
+   * 未启用 hash 部署时为 `""`。
+   */
+  readonly buildDirHash: string;
+};
+
+/** @public */
+export interface CreateLibraryViteConfigOptions {
+  rootDir: string;
+  command: "serve" | "build" | string;
+  /**
+   * Vite mode。与应用工厂对齐，便于 `defineConfig(({ command, mode }) => ...)`；
+   * 本工厂不据此切换 Hash 或 public-config。
+   */
+  mode: string;
+
+  /**
+   * 与 Vite `resolve.alias` 相同：
+   * - `Record<string, string>`
+   * - `{ find, replacement }[]`
+   *
+   * 不默认 `@` / `@assets` / `@service`。
+   */
+  alias?: AliasOptions;
+
+  /**
+   * 库入口，相对 `rootDir`。
+   * @defaultValue "src/index.ts"
+   */
+  entry?: string;
+
+  /**
+   * UMD / IIFE 全局变量名。`formats` 含 `umd` 或 `iife` 的 **build** 必填。
+   */
+  name?: string;
+
+  /**
+   * 产物目录。
+   * @defaultValue "lib"
+   */
+  outDir?: string;
+
+  /**
+   * 产物文件名。未传时：单一 format 为 `index.js`；多 format 时 ESM 为 `index.js`，其余为 `index.<format>.js`。
+   */
+  fileName?: string | ((format: string, entryName: string) => string);
+
+  /**
+   * CSS 产物名（不含扩展名）。库入口若导入样式则写出 `<cssFileName>.css`。
+   * @defaultValue "index"
+   */
+  cssFileName?: string;
+
+  /**
+   * @defaultValue ["umd"]（对齐 webpack `libraryTarget: "umd"`）
+   */
+  formats?: LibraryFormats[];
+
+  /**
+   * 构建时外置的依赖。仅 `command === "build"` 生效；serve 预览会打进包，便于本地联调。
+   * - 未传：`react` / `react-dom`（含子路径如 `react/jsx-runtime`）
+   * - `false`：不外置
+   * - 数组：整表替换默认值（追加请展开 `DEFAULT_LIBRARY_EXTERNALS`）
+   */
+  externals?: (string | RegExp)[] | false;
+
+  /**
+   * UMD / IIFE `output.globals`。会与默认 React 全局名及字符串 external 的包名合并；此项覆盖同名键。
+   */
+  globals?: Record<string, string>;
+
+  useHttps?: boolean;
+  /**
+   * 开发服务器启动时是否自动打开浏览器（映射 `server.open`）。
+   * - `true`（默认）：打开站点根
+   * - `false`：不打开
+   * - `string`：作为 URL pathname 打开
+   */
+  openBrowser?: boolean | string;
+  devProxy?: Record<string, ProxyOptions>;
+  /**
+   * React Compiler：
+   * - `true`：build 与 serve 都开
+   * - `"build-only"`（默认）：仅 build，且可用 `REACT_COMPILER=false` 关闭
+   * - `false`：关闭
+   */
+  reactCompiler?: ReactCompilerMode;
+  /**
+   * 是否启用 `@vitejs/plugin-react`。
+   * @defaultValue true
+   */
+  react?: boolean;
+  /**
+   * SVG React 组件通道（`import Icon from "./icon.svg?react"`）。
+   * 未传 / `false` 关闭；`true` 或选项对象启用。
+   */
+  svgr?: boolean | SvgReactOptions;
+  /**
+   * Less 预处理器选项，映射到 `css.preprocessorOptions.less`。
+   */
+  less?: LessOptions;
+
+  /**
+   * 本地预览 HTML，相对 `rootDir`。仅 `command === "serve"` 时交给 `vite-plugin-html`。
+   * 未传则使用 Vite 默认根目录 `index.html`。不默认 `example/`。
+   */
+  previewHtml?: string;
+
+  /**
+   * 构建开始回调（Vite `buildStart`）。仅 `command === "build"` 时挂载。
+   */
+  onRun?: () => void;
+  /**
+   * 产物写盘成功后的回调（sequential post `writeBundle`）。
+   * 仅 `command === "build"` 时挂载。
+   */
+  onDone?: () => void | Promise<void>;
+
+  /** 追加插件（排在内置插件之后、生命周期回调之前） */
+  plugins?: PluginOption[];
+  /** 经 mergeConfig 合并进最终配置 */
+  vite?: UserConfig;
+  /** 最终回调，可任意改 */
+  configure?: (config: UserConfig) => UserConfig;
+}

package/src/vitest-types.ts

@@ -0,0 +1,20 @@
+import type { AliasOptions, PluginOption } from "vite";
+import type { ViteUserConfig as VitestUserConfig } from "vitest/config";
+
+export interface CreatePackageVitestConfigOptions {
+  packageRoot: string;
+  /**
+   * 与 Vite `resolve.alias` 相同：
+   * - `Record<string, string>`
+   * - `{ find, replacement }[]`
+   */
+  alias?: AliasOptions;
+  react?: boolean;
+  stubLess?: boolean;
+  environment?: "happy-dom" | "jsdom" | "node" | "edge-runtime" | string;
+  include?: string[];
+  setupFiles?: string[];
+  plugins?: PluginOption[];
+  vite?: VitestUserConfig;
+  configure?: (config: VitestUserConfig) => VitestUserConfig;
+}

package/src/vitest.ts

@@ -0,0 +1,2 @@
+export { createPackageVitestConfig } from "./create-package-vitest-config.ts";
+export type { CreatePackageVitestConfigOptions } from "./vitest-types.ts";

package/templates/src/vite-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="vite/client" />
+/// <reference types="@hzab/vite-config/client" />

package/templates/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "jsx": "react-jsx",
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/templates/vite.config.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vite";
+import { createViteConfig } from "@hzab/vite-config";
+
+const rootDir = path.dirname(fileURLToPath(import.meta.url));
+
+// 从应用 package.json 读取版本号（勿注入 @hzab/vite-config 自身的版本）
+const { version } = JSON.parse(readFileSync(path.resolve(rootDir, "package.json"), "utf-8"));
+
+export default defineConfig(({ command, mode }) =>
+  createViteConfig({
+    rootDir,
+    command,
+    mode,
+    vite: {
+      define: {
+        // 源码中的 process.env.PACKAGE_VERSION 在构建时替换为应用版本号
+        "process.env.PACKAGE_VERSION": JSON.stringify(version),
+        // 自定义键示例：透传构建时环境变量（未设置时回退默认值）
+        // "process.env.CUSTOM_KEY": JSON.stringify(process.env.CUSTOM_KEY ?? ""),
+      },
+    },
+  }),
+);