@hzab/vite-config 0.0.2-alpha.0

package/docs/api.md

@@ -0,0 +1,366 @@
+# API
+
+## `createViteConfig(options?)`
+
+默认工厂，面向新项目；等价于 `createAppViteConfig` 的快捷入口，但部分默认值不同。显式传入
+的选项始终优先（内部最后展开 `options`）：
+
+| 选项            | `createViteConfig` 默认     | `createAppViteConfig` 默认      |
+| --------------- | --------------------------- | ------------------------------- |
+| `rootDir`       | `process.cwd()`             | 必填                            |
+| `command`       | `"serve"`                   | 必填                            |
+| `mode`          | `"development"`             | 必填                            |
+| `openBrowser`   | `false`（不自动打开浏览器） | `true`（开发启动自动打开）      |
+| `reactCompiler` | `false`（关闭）             | `"build-only"`（仅 build 启用） |
+
+其余选项默认值与 [`createAppViteConfig`](#createappviteconfigoptions) 一致。
+
+## `createAppViteConfig(options)`
+
+组装应用 Vite 配置。返回值可直接交给 `defineConfig` / `vite.build`；并附带只读
+`buildDirHash`（本次 hash 子目录名；未启用时为 `""`）。该字段为非可枚举，展开配置时不会
+写入 Vite 选项。
+
+```ts
+const config = createAppViteConfig({ /* ... */ hashDeploy: true });
+config.buildDirHash; // e.g. "a1b2c3d4e5f6-1710000000000"
+```
+
+### 策略选项
+
+| 字段                           | 说明                                                                                                                                                                  |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rootDir` / `command` / `mode` | 必填上下文；`rootDir` 同时作为 Vite `root` 和默认 Git 仓库目录                                                                                                        |
+| `repositoryRoot`               | 可选 Git 仓库目录；生成 Hash 时覆盖默认的 `rootDir`，适用于应用位于仓库子目录的场景                                                                                   |
+| `alias`                        | 与 Vite `resolve.alias` 相同（`Record<string, string>` 或 `{ find, replacement }[]`）                                                                                 |
+| `useHttps`                     | 开发 HTTPS + basic-ssl                                                                                                                                                |
+| `openBrowser`                  | 开发启动自动打开浏览器（映射 `server.open`）；默认 `true`；`false` 关闭；`string` 为 pathname；也可经 `vite.server.open` 覆盖                                         |
+| `hashDeploy`                   | build 时启用 hash 子目录部署（且 `mode !== "development"`）                                                                                                           |
+| `hashTimestamp`                | Hash 目录时间戳格式。默认 `"epoch"`（`{commit}-{Date.now()}`）；`"datetime"` 为本地时区 `{commit}-YYYY-MM-DD-HH-mm-ss`                                                |
+| `base`                         | 构建资源公共路径（Vite `base`）；未传则默认 `"./"`；可传 `https://cdn.example.com/app/`；hash 模式下实际为 `{base}{hash}/`                                            |
+| `deployRoot`                   | 产物根目录，默认 `"dist"`；hash 模式下为 `<deployRoot>/<hash>/` 的父目录                                                                                              |
+| `hashCleanup`                  | `{ keep }`；成功构建后保留的 Hash 版本总数（含本次），`keep` 须为正整数；未传则永久保留                                                                               |
+| `publicAssets`                 | `{ dir? }`；默认启用，复制到产物 `public/` 子目录；传 `false` 恢复 Vite 默认 publicDir                                                                                |
+| `publicConfig`                 | `{ mode, sourceGlob?, dest? }`；默认复制到站点根 `config/`；`dest` 可覆盖（如 `"public/config"`）；传 `false` 关闭                                                    |
+| `copy`                         | 额外静态复制。传 `{ targets, silent?, watch?, hook? }` 或直接传 `targets` 数组；独立插件 `copyPlugin()`                                                               |
+| `htmlData`                     | 注入 HTML 模板的 EJS 数据，与内置 `PUBLIC_PATH` 合并；HTML `PUBLIC_PATH` 始终由工厂计算，消费方同名键会被覆盖                                                         |
+| `devProxy`                     | `server.proxy`                                                                                                                                                        |
+| `reactCompiler`                | `true` \| `"build-only"`（默认）\| `false`                                                                                                                            |
+| `react`                        | 是否启用 `@vitejs/plugin-react`，默认 `true`                                                                                                                          |
+| `svgr`                         | SVG 组件通道；默认关。`true` 或 SVGR 选项对象启用 `import Icon from "./icon.svg?react"`；普通 `*.svg` 仍为 URL。需可选 peer `@svgr/*`                                 |
+| `less`                         | Less 预处理器：`additionalData` / `modifyVars` / `javascriptEnabled` → `css.preprocessorOptions.less`                                                                 |
+| `onRun` / `onDone`             | 构建生命周期。仅 `command === "build"` 时挂载：`onRun` → `buildStart`；`onDone` 在 Hash 根入口写入之后（sequential post `writeBundle`）。Hash 写入失败不调用 `onDone` |
+
+所有 build 默认设置 `base: "./"`，生成的 JS、CSS、图片和 module preload 均使用相对路径；
+开发服务器仍使用 Vite 默认 base。需要把产物挂到固定 HTTPS/CDN 目录时，直接传工厂选项
+`base`（会自动补尾 `/`）：
+
+```ts
+createAppViteConfig({
+  // ...
+  base: "https://cdn.example.com/app/", // → 资源 URL 前缀
+});
+```
+
+未使用 `hashDeploy` 时，仍可通过 `vite` / `configure` 覆盖 `base`；启用 hash 后不得改掉
+工厂生成的最终 `base`（见下方契约）。
+
+### copy 示例
+
+```ts
+createAppViteConfig({
+  // ...
+  copy: [
+    {
+      src: "node_modules/some-sdk/assets/**/*",
+      dest: "sdk",
+      rename: { stripBase: 3 },
+    },
+  ],
+  // 或完整选项：copy: { targets: [...], silent: true }
+});
+```
+
+也可脱离工厂使用 `copyPlugin()`（同族于 `publicAssetsPlugin` / `publicConfigPlugin`）。
+
+### htmlData 示例
+
+模板使用 EJS 插值（与现有 `<%= PUBLIC_PATH %>` 相同）：
+
+```html
+<title><%= APP_TITLE %></title> <link rel="icon" href="<%= PUBLIC_PATH %>public/icons.svg" />
+```
+
+```ts
+createAppViteConfig({
+  // ...
+  htmlData: { APP_TITLE: "My App" },
+});
+```
+
+`PUBLIC_PATH` 仍由工厂按 `base` / Hash 写入；`htmlData.PUBLIC_PATH` 不会覆盖它。
+
+相对 Hash 时，**子目录 HTML** 的 `PUBLIC_PATH` 是 `./`（资源相对该子目录）；**JS** 里的
+`import.meta.env.PUBLIC_PATH` 是 `./{hash}/`，给打开根 `index.html` 后的 `fetch` / 动态 URL
+用。两者不是同一个值。Vite `base` / `import.meta.env.BASE_URL` 仍为 `./`，不要改它。
+
+```ts
+fetch(`${import.meta.env.PUBLIC_PATH}public/data.json`);
+// 相对 hash：./{hash}/public/data.json
+```
+
+类型：
+
+```ts
+/// <reference types="@hzab/vite-config/client" />
+```
+
+`vite.define` / `configure` 里的同名键会被工厂覆盖。必须写成静态成员
+`import.meta.env.PUBLIC_PATH`，不要解构。
+
+### publicConfig `dest` 示例
+
+```ts
+// 默认：产物 /config/config.js
+publicConfig: { mode }
+
+// 对齐 webpack 等：产物 /public/config/config.js（需同步改 index.html 引用）
+publicConfig: { mode, dest: "public/config" }
+```
+
+### 外部自定义
+
+| 字段        | 说明                                          |
+| ----------- | --------------------------------------------- |
+| `plugins`   | 追加插件（内置之后、`onRun` / `onDone` 之前） |
+| `vite`      | 任意 `UserConfig`，经 `mergeConfig` 合并      |
+| `configure` | `(config) => config` 最终回调                 |
+
+**合并顺序：** `base(options) → mergeConfig(base, vite) → configure(final)`，之后工厂写入
+`import.meta.env.PUBLIC_PATH`（覆盖 `vite.define` / `configure` 里的同名键）。
+
+`plugins` 排在 Hash 部署等内置插件之后。`onRun` / `onDone` 再挂在其后，因此 `onDone` 能读到
+`hash.txt` 与根 `index.html`。消费方 `writeBundle`（sequential post）若抛错，不会调用 `onDone`。
+
+### Hash 部署契约
+
+启用 `hashDeploy` 后：默认 Vite `base` 仍为相对 `./`，构建结束时为根入口的相对
+`src` / `href` 增加 Hash 前缀；Hash 子目录入口中的 HTML `PUBLIC_PATH` 保持
+`./`，因此 `assets/`、`public/`、`config/` 均相对于该子目录。JS
+`import.meta.env.PUBLIC_PATH` 则为 `./{hash}/`（打开根入口时拼静态文件）。传入绝对 `base`
+（`https://…` / `http://…` / `/…`）时，最终 Vite `base` 与两个入口的资源前缀均为
+`{base}{hash}/`。
+
+默认产物为（`deployRoot` 默认 `"dist"`）：
+
+- `<deployRoot>/<hash>/`：本次完整构建；
+- `<deployRoot>/index.html`：从 hash 目录复制的部署入口；
+- `<deployRoot>/hash.txt`：当前 hash 目录名。
+
+工厂返回值上的 `buildDirHash` 与上述 `<hash>` / `hash.txt` 内容一致。
+其中 commit hash 默认从 `rootDir` 读取；应用位于 monorepo 子目录时可传 `repositoryRoot`
+显式指定仓库目录，不依赖启动 Vite 时的进程工作目录。默认目录名为 `{commit}-{Date.now()}`；
+`hashTimestamp: "datetime"` 时改为本地时区 `{commit}-YYYY-MM-DD-HH-mm-ss`。
+
+默认不清理旧 Hash 目录，回滚版本的保留期限与清理由部署系统负责。消费方也可配置
+`hashCleanup: { keep }`：插件在本次构建及根入口成功写入后，按目录名中的时间戳清理旧版本，
+最终保留包含本次构建在内的最新 `keep` 个版本。清理只匹配工厂生成的
+`<12 位 git hash>-<timestamp>` / `local-<timestamp>` 目录（`timestamp` 为毫秒 epoch 或
+`YYYY-MM-DD-HH-mm-ss`），不会删除部署根目录中的其他文件或目录。混用两种格式时按解析后的真实时间排序。
+
+```ts
+createAppViteConfig({
+  // ...
+  hashDeploy: true,
+  deployRoot: "artifacts", // → artifacts/<hash>/ + artifacts/index.html + artifacts/hash.txt
+  hashCleanup: { keep: 3 }, // 本次成功构建后仅保留最新 3 个 Hash 版本
+  hashTimestamp: "datetime", // → artifacts/a1b2c3d4e5f6-2026-08-21-18-54-00/
+  base: "https://cdn.example.com/releases/", // → base 实际为该 URL + <hash>/
+});
+```
+
+最终 `build.outDir` 必须以生成的 `<hash>` 目录结尾。除 `deployRoot` 外，仍可通过
+`configure` 修改父目录（例如把 `dist/<hash>` 改为 `artifacts/<hash>`）；插件会从 Vite 的最终
+resolved config 推导部署根目录。修改时不得覆盖 Hash 部署生成的最终 `base`（相对
+`./{hash}/` 或 `{customBase}{hash}/`），否则构建会直接报错，避免产出路径错误但表面成功。
+
+### alias 示例（与 Vite 原配置一致）
+
+```ts
+alias: {
+  "@": path.resolve(rootDir, "./src"),
+  "@hzab/utils": path.resolve(rootDir, "./packages/utils/src/index.ts"),
+  "@hzab/utils/src": path.resolve(rootDir, "./packages/utils/src"),
+}
+
+// 或数组形式
+alias: [
+  { find: "@", replacement: path.resolve(rootDir, "./src") },
+]
+```
+
+### less 示例（等价 webpack `less-loader`）
+
+| webpack `lessLoaderOptions`  | 工厂 `less`                                   |
+| ---------------------------- | --------------------------------------------- |
+| `additionalData`             | `additionalData`                              |
+| `modifyVars`                 | `modifyVars`                                  |
+| `javascriptEnabled`          | `javascriptEnabled`                           |
+| （无，webpack `~` 前缀约定） | `resolveTilde`（默认 `false`，需手动 `true`） |
+
+```ts
+createAppViteConfig({
+  // ...
+  less: {
+    additionalData: `@import "${path.resolve(rootDir, "src/assets/styles/variables.less")}";`,
+    // modifyVars: { '@primary-color': '#1890ff' },
+    // javascriptEnabled: true,
+    // resolveTilde: true, // 开启 `~` 解析（默认关闭）
+  },
+});
+```
+
+`~antd/...` 这类 webpack 「~」前缀写法（含第三方包自带的 `~antd` 导入）**默认不解析**；
+项目含 `~antd` 时设 `less.resolveTilde: true` 开启，自动从 node_modules 解析，无需改写为裸包名。
+
+### SVG 双通道（`svgr`）
+
+资源通道不封装：`import url from "./icon.svg"` 走 Vite 默认 URL。组件通道默认关闭；启用后使用社区 query `?react`（不兼容 webpack 的 `?svgEle`）：
+
+```ts
+createAppViteConfig({
+  // ...
+  svgr: true,
+  // svgr: { icon: true },
+});
+```
+
+```tsx
+import logoUrl from "./logo.svg";
+import Logo from "./logo.svg?react";
+
+<img src={logoUrl} alt="" />
+<Logo className="icon" />
+```
+
+类型：
+
+```ts
+/// <reference types="@hzab/vite-config/svg-react" />
+```
+
+或在 tsconfig `compilerOptions.types` 数组中加入 `"@hzab/vite-config/svg-react"`（也可用
+副作用导入 `import '@hzab/vite-config/svg-react'` 等价加载）。该入口为纯类型入口（运行时为
+空模块），声明 `*.svg?react` 默认导出 `FunctionComponent<SVGProps<SVGSVGElement>>`，仅供
+类型引用，不产生运行时行为。
+
+运行时需安装可选 peer `@svgr/core`、`@svgr/plugin-jsx`；未关 `svgo` 时还需 `@svgr/plugin-svgo`。也可直接使用独立插件 `svgReactPlugin()`。
+
+## `createLibraryViteConfig(options)`
+
+组装组件库 Vite 配置。`command === "build"` 走 `build.lib`（默认 UMD → `lib/index.js`）；
+`command === "serve"` 是本地预览应用，不启用 lib / externals。不挂 Hash 部署、public 复制或
+public-config。
+
+```ts
+import path from "node:path";
+import { defineConfig } from "vite";
+import { createLibraryViteConfig, DEFAULT_LIBRARY_EXTERNALS } from "@hzab/vite-config";
+
+export default defineConfig(({ command, mode }) =>
+  createLibraryViteConfig({
+    rootDir: __dirname,
+    command,
+    mode,
+    name: "MyLib", // formats 含 umd / iife 的 build 必填
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+    // externals: [...DEFAULT_LIBRARY_EXTERNALS, "antd"],
+    // previewHtml: "preview/index.html",
+  }),
+);
+```
+
+### 策略选项
+
+| 字段                                        | 说明                                                                                                                                                     |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rootDir` / `command` / `mode`              | 必填上下文；`mode` 与应用工厂对齐，本工厂不据此切换 Hash                                                                                                 |
+| `alias`                                     | 与 Vite `resolve.alias` 相同；**不**默认 `@` / `@assets` / `@service`                                                                                    |
+| `entry`                                     | 库入口，相对 `rootDir`。默认 `"src/index.ts"`                                                                                                            |
+| `name`                                      | UMD / IIFE 全局名。`formats` 含 `umd` 或 `iife` 的 build 必填                                                                                            |
+| `outDir`                                    | 产物目录。默认 `"lib"`                                                                                                                                   |
+| `fileName`                                  | 产物文件名。未传时：单一 format 为 `index.js`；多 format 时 ESM 为 `index.js`，其余 `index.<format>.js`                                                  |
+| `cssFileName`                               | CSS 产物名（不含扩展名）。默认 `"index"`                                                                                                                 |
+| `formats`                                   | 默认 `["umd"]`（对齐 webpack `libraryTarget: "umd"`）                                                                                                    |
+| `externals`                                 | 仅 build 生效。未传：`react` / `react-dom`（含子路径如 `react/jsx-runtime`）；`false` 不外置；数组**整表替换**（追加请展开 `DEFAULT_LIBRARY_EXTERNALS`） |
+| `globals`                                   | UMD / IIFE 全局名。与 React 默认及字符串 external 的包名合并                                                                                             |
+| `previewHtml`                               | 仅 serve：交给 `vite-plugin-html` 的模板，相对 `rootDir`。未传则用根目录 `index.html`。**不**默认 `example/`                                             |
+| `useHttps` / `openBrowser` / `devProxy`     | 同应用工厂；仅 serve                                                                                                                                     |
+| `react` / `reactCompiler` / `svgr` / `less` | 同应用工厂                                                                                                                                               |
+| `onRun` / `onDone`                          | 仅 `command === "build"` 时挂载                                                                                                                          |
+| `plugins` / `vite` / `configure`            | 同应用工厂。合并顺序：`base(options) → mergeConfig(base, vite) → configure(final)`                                                                       |
+
+默认导出常量：`DEFAULT_LIBRARY_EXTERNALS`（`react` / `react-dom`）、`DEFAULT_LIBRARY_GLOBALS`
+（`react → React`、`react-dom → ReactDOM`）。
+
+serve 预览会把依赖打进包，便于本地联调；不要用应用工厂的 `hashDeploy` 去包一层。预览页把
+`index.html` 放在包根，或传 `previewHtml`。`publicDir` 固定为 `false`（对齐 webpack 组件模式
+不复制 public）；需要静态目录时经 `vite.publicDir` 打开。
+
+## `createPackageVitestConfig(options)`
+
+从独立入口导入：
+
+```ts
+import { createPackageVitestConfig } from "@hzab/vite-config/vitest";
+```
+
+| 字段                             | 说明                                                                   |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| `packageRoot`                    | 包根目录（`root`）                                                     |
+| `alias`                          | 与 Vite `resolve.alias` 相同                                           |
+| `react` / `stubLess`             | 可选插件                                                               |
+| `environment`                    | 默认 `happy-dom`（需安装可选 peer `happy-dom`；纯逻辑包可传 `"node"`） |
+| `include` / `setupFiles`         | 测试发现                                                               |
+| `plugins` / `vite` / `configure` | 同应用工厂                                                             |
+
+`vite`、`configure` 的参数与返回值，以及工厂返回值均使用 Vitest 的 `ViteUserConfig`
+类型，包含 `test` 字段校验；传入无效的 Vitest 配置项会在 TypeScript 编译期报错。
+
+## 独立插件
+
+可脱离工厂自行组装：
+
+- `relativeBasePlugin(deployPath)`
+- `hashDeployPlugin({ rootDir, buildDirStr, publicPath, cleanup? })`
+- `lifecyclePlugin({ onRun?, onDone? })`
+- `copyPlugin({ targets, silent?, watch?, hook? })`（也可直接传 `targets` 数组）
+- `publicAssetsPlugin({ dir? })`
+- `publicConfigPlugin({ sourceGlob, dest? })`
+- `reactCompilerPlugin({ command, mode? })`
+- `svgReactPlugin({ svgo?, icon?, ... })`
+- `stubLessPlugin()`
+- `getCommitHash(repositoryRoot?)`
+- `createHashBuildDirName(repositoryRoot?, now?)`（仍兼容旧的 `createHashBuildDirName(now)`）
+- `createHashBuildDirName({ repositoryRoot?, now?, timestampFormat? })`
+
+`stubLessPlugin()` 会将普通 `.less` 作为空模块处理；`.module.less` 的默认导出是 identity
+stub，访问 `styles.foo` 会得到 `"foo"`，无需在单测中加载 Less 编译链。
+
+## peerDependencies
+
+入口模块会静态装载配置工厂和独立插件，因此以下 peer 均为必选：
+
+`vite`、`@vitejs/plugin-react`、`@vitejs/plugin-basic-ssl`、`@rolldown/plugin-babel`、
+`vite-plugin-html`、`vite-plugin-static-copy`。
+
+`vitest` 仅在导入 `@hzab/vite-config/vitest`、使用 `createPackageVitestConfig` 时需要安装；
+包根入口不引用 Vitest 运行时或类型。
+
+`@svgr/core`、`@svgr/plugin-jsx`、`@svgr/plugin-svgo` 为可选 peer：仅在启用 `svgr` /
+`svgReactPlugin` 且实际导入 `*.svg?react` 时加载；未启用时不必安装。
+
+`happy-dom` 为可选 peer：仅在使用 `createPackageVitestConfig` 且保留默认
+`environment: "happy-dom"` 时需要安装；纯逻辑测试可传 `environment: "node"` 免装。