@hzab/vite-config 0.0.2-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+## Unreleased
+
+- 工厂注入 `import.meta.env.PUBLIC_PATH`：相对 Hash 为 `./{hash}/`，供根入口 JS `fetch`
+  静态文件；不改 Vite `base` / `BASE_URL`。HTML 子目录模板 `PUBLIC_PATH` 仍为 `./`。
+  类型入口：`@hzab/vite-config/client`。
+
+## 0.0.2-alpha.0
+
+### Patch Changes
+
+- less ~ 编译问题修复
+
+## 0.0.1
+
+首个发布于企业私有 npm Registry 的版本（阿里云企业版 Packages，ld / old 双实例）。版本线从
+本仓库独立开始，迁移自旧 `@ccc` 仓库的既有能力随本版本一并提供：
+
+- api-extractor 注释类警告清零：主入口导出符号统一补 `@public` release tag（overloaded 函数
+  `createHashBuildDirName` 每个 overload 均带）；`@default` 全部改标准 TSDoc `@defaultValue`；
+  注释中的 `@vitejs/plugin-react` 以反引号包裹转义。api-report 零警告（此前为 warning 级不阻塞）。
+
+- 文档化 `createViteConfig` 与 `createAppViteConfig` 的默认值差异：默认工厂
+  `reactCompiler: false` / `openBrowser: false`（`rootDir` / `command` / `mode` 默认
+  `process.cwd()` / `"serve"` / `"development"`）；完整工厂 `reactCompiler: "build-only"` /
+  `openBrowser: true`（前三项必填）。README 与 docs/api.md 同步补充对照表与显式覆盖说明。
+
+- `@hzab/vite-config/svg-react` 补齐运行时入口（空模块），子路径现在可被 import / require
+  解析；并文档化消费方引用方式：tsconfig `types` 数组、`/// <reference types=... />` 或副作用
+  导入。类型声明内容不变（`*.svg?react` → `FunctionComponent<SVGProps<SVGSVGElement>>`）。
+
+- Hash 目录时间戳支持 `hashTimestamp: "datetime"`：本地时区 `YYYY-MM-DD-HH-mm-ss` 作为子目录名；
+  默认仍为毫秒 epoch。`hashCleanup` 同时识别两种格式，并按真实时间排序。
+  `createHashBuildDirName` 增加 `{ repositoryRoot?, now?, timestampFormat? }` 选项重载。
+
+- 新增通用复制插件 `copyPlugin` 与工厂选项 `copy`：封装 `vite-plugin-static-copy`，可传完整选项或
+  `targets` 数组；`publicAssetsPlugin` / `publicConfigPlugin` 改为基于它组装。
+- 新增 `htmlData`：注入 HTML 模板 EJS 数据，与内置 `PUBLIC_PATH` 合并；`PUBLIC_PATH` 始终由工厂
+  按 base / Hash 计算。
+
+- 新增 `createLibraryViteConfig` 组件库工厂：build 默认 UMD 产出 `lib/index.js`，外置
+  `react` / `react-dom`（含子路径）；serve 为预览应用、不外置、无 Hash。`externals` 整表替换
+  默认值；不默认 `example/` 或 antd / Formily。UMD / IIFE build 须传 `name`。
+
+- 新增 `onRun` / `onDone` 构建生命周期回调（对齐 webpack）：仅 `command === "build"` 时挂载；
+  `onDone` 排在 Hash 根入口 / `hash.txt` 写入之后，写入失败不调用。独立插件
+  `lifecyclePlugin()`；Hash 插件 `writeBundle` 改为 sequential post。
+
+- 新增可选 SVG 组件通道：`svgr` / `svgReactPlugin` 将 `*.svg?react` 编成 React 组件；
+  普通 `*.svg` 仍走 Vite 默认 URL。默认关闭，不搬 webpack 的 `?svgEle`；`@svgr/*` 为可选
+  peer，仅在真正转换时加载。类型入口：`@hzab/vite-config/svg-react`。
+- 支持独立 npm 发布：入口改为 `dist/` ESM 与类型声明，增加受限 `exports`、发布前构建及
+  public access 配置；保留根入口、`/vitest` 与 `/src/*` 兼容入口，并随包提供 `src/`
+  供 source map 调试和源码查看。
+- 新增 `createPackageVitestConfig` 默认值/合并顺序，以及 `publicAssetsPlugin` /
+  `publicConfigPlugin` 复制结果的独立回归测试。
+- 新增 React Compiler 的 build / serve 转换回归：覆盖插件开关分支，并用 React 17 风格
+  函数组件验证 `reactCompiler: true` 下的最小构建与开发转换；默认仍为 `"build-only"`。
+- `stubLessPlugin()` 现在为 `.module.less` 提供 identity 默认导出，支持测试代码通过
+  `styles.foo` 获取稳定类名；普通 Less 仍作为空模块处理。
+- Hash 目录的 commit hash 默认从应用 `rootDir` 获取，并新增 `repositoryRoot` 显式仓库目录；
+  `getCommitHash` / `createHashBuildDirName` 同步支持仓库目录，不再依赖进程工作目录。
+- 新增 `hashCleanup: { keep }`：Hash 构建成功后可按消费方配置保留最新版本；默认不清理，
+  且只删除工厂命名的旧 Hash 目录。
+- 移除未接入工厂的 `HashDeployOptions` 公开类型；Hash 部署继续使用
+  `CreateAppViteConfigOptions` 顶层的 `hashDeploy` 与 `deployRoot` 配置。
+- `createPackageVitestConfig` 改用 Vitest 的 `ViteUserConfig`，让 `vite` 覆盖、
+  `configure` 回调、工厂返回值及内置 `test` 配置保持类型安全；并迁至独立
+  `@hzab/vite-config/vitest` 入口，避免根入口产生 Vitest 类型依赖。
+- 修复相对 Hash 部署中子目录入口的 `PUBLIC_PATH` 重复 Hash，并让根入口统一改写
+  `assets/`、`public/`、`config/` 等相对资源引用。
+- 将入口模块静态加载的 Vite 插件声明为必装 peer；仅保留 `vitest` 为 optional peer。
+- 新增 `base`：可直接设置构建资源公共路径（含 HTTPS/CDN 目录）；`hashDeploy` 下实际为
+  `{base}{hash}/`，并放宽插件对最终 `base` 的校验。
+- `createAppViteConfig` 返回值增加只读 `buildDirHash`（本次 hash 子目录名；未启用时为 `""`）。
+- 新增 `deployRoot`：可配置构建产物根目录（hash 模式下为 hash 子目录与根入口的父目录，默认 `"dist"`）。
+- 开发服务器默认自动打开浏览器（`openBrowser` / `server.open`）；传 `false` 可关闭。
+- 修复 Hash 部署对 `dist/` 的硬编码，改为从 Vite 最终配置解析部署目录。
+- Hash 子目录改用 Vite 原生相对 `base`，根入口按最终 `assetsDir` 增加 Hash 前缀，并校验
+  `root`、`base` 与 `outDir` 契约。
+- 所有非 Hash build 同样默认使用 `base: "./"`，避免产物依赖站点根路径。
+- 增加 Hash 构建、定制部署根目录和非法 `outDir` 的集成测试。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CaiYansong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# @hzab/vite-config
+
+可发布的 Vite / Vitest 配置组件：工厂 + 可组合插件。消费方传入策略。
+
+默认工厂 `createViteConfig(options?)` 适合新项目；完整控制仍使用 `createAppViteConfig`。初始化文件见 [`templates/`](./templates/)。
+
+## 安装
+
+```bash
+pnpm add @hzab/vite-config
+# peer：vite、@vitejs/plugin-react、@vitejs/plugin-basic-ssl、
+# @rolldown/plugin-babel、vite-plugin-html、vite-plugin-static-copy
+# 使用 Vitest 工厂时另装 vitest
+# 使用 Vitest 工厂默认 happy-dom 环境时另装 happy-dom
+# 使用 svgr / *.svg?react 时另装 @svgr/core、@svgr/plugin-jsx、@svgr/plugin-svgo
+```
+
+本仓通过 pnpm workspace 引用；包入口统一指向 `dist/` 编译产物。
+
+## 发布
+
+```bash
+# 仓库根目录
+pnpm --filter @hzab/vite-config pack --dry-run
+pnpm --filter @hzab/vite-config publish
+```
+
+`prepack` 会先执行 TypeScript 构建。默认入口始终使用 `dist/` 中的 ESM 与类型声明；
+包同时包含 `src/`，便于 source map 调试和源码查看，不要求消费方编译 TypeScript。
+`@hzab/vite-config/src/*` 兼容入口仍解析到 `dist/`，不会绕过编译产物。作用域包默认按
+public access 发布；若使用私有 registry，请在发布环境覆盖对应 npm 配置。
+
+## 快速使用
+
+### 应用 Vite
+
+```ts
+import path from "node:path";
+import { defineConfig } from "vite";
+import { createAppViteConfig } from "@hzab/vite-config";
+
+export default defineConfig(({ command, mode }) =>
+  createAppViteConfig({
+    rootDir: __dirname,
+    command,
+    mode,
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+      "@hzab/utils": path.resolve(__dirname, "./packages/utils/src/index.ts"),
+      "@hzab/utils/src": path.resolve(__dirname, "./packages/utils/src"),
+    },
+    useHttps: true,
+    // openBrowser: false, // 默认 true；关闭自动打开浏览器
+    hashDeploy: mode !== "development",
+    // repositoryRoot: path.resolve(__dirname, "../.."), // 应用位于仓库子目录时显式指定
+    hashCleanup: { keep: 3 }, // 可选；成功构建后保留最新 3 个 Hash 版本
+    // hashTimestamp: "datetime", // 可选；目录名用本地 YYYY-MM-DD-HH-mm-ss 代替毫秒时间戳
+    publicConfig: { mode },
+    // copy: [{ src: "vendor/assets/**/*", dest: "vendor" }],
+    // htmlData: { APP_TITLE: "My App" },
+    // svgr: true, // 启用 import Icon from "./icon.svg?react"；需可选 peer @svgr/*
+    // plugins / vite / configure 可继续扩展
+  }),
+);
+```
+
+`createAppViteConfig` 默认 `openBrowser: true`（开发启动自动打开浏览器）与
+`reactCompiler: "build-only"`（仅生产构建启用）。默认工厂 `createViteConfig` 面向新项目，
+两处默认值不同：
+
+| 选项                           | `createViteConfig`（默认工厂）                | `createAppViteConfig`（完整工厂） |
+| ------------------------------ | --------------------------------------------- | --------------------------------- |
+| `openBrowser`                  | `false`（不自动打开浏览器）                   | `true`（开发启动自动打开）        |
+| `reactCompiler`                | `false`（关闭）                               | `"build-only"`（仅 build 启用）   |
+| `rootDir` / `command` / `mode` | `process.cwd()` / `"serve"` / `"development"` | 必填，无默认                      |
+
+其余选项默认值两工厂一致。显式传入的选项始终生效（`createViteConfig` 内部最后展开
+`options`）；需要完整工厂行为时传 `openBrowser: true`、`reactCompiler: "build-only"`。
+
+Hash 部署使用 Vite 原生 `base`，默认输出
+`dist/<hash>/`、`dist/index.html` 与 `dist/hash.txt`。可用 `deployRoot` 改父目录（如
+`artifacts`）；若经 `configure` 自定义 `build.outDir`，必须保留末级 `<hash>` 目录。本次
+hash 目录名也可从返回值的 `buildDirHash` 读取。JS 里用 `import.meta.env.PUBLIC_PATH`
+（相对 Hash 为 `./{hash}/`）拼 `public/` 等静态文件，不要用 `BASE_URL`；类型入口
+`@hzab/vite-config/client`。默认永久保留旧版本；消费方可通过
+`hashCleanup: { keep }` 配置成功构建后的保留数量。commit hash 默认从 `rootDir` 获取，也可用
+`repositoryRoot` 指定仓库目录，不依赖启动命令的工作目录。默认目录名为
+`{commit}-{Date.now()}`；`hashTimestamp: "datetime"` 时改为本地时区
+`{commit}-YYYY-MM-DD-HH-mm-ss`。详见
+[Hash 部署契约](./docs/api.md#hash-部署契约)。
+
+所有 build 默认使用 `base: "./"`。若产物部署在固定 HTTPS/CDN 目录，直接传工厂选项
+`base: "https://cdn.example.com/app/"`；启用 `hashDeploy` 时实际前缀为 `{base}{hash}/`。
+
+### `*.svg?react` 类型声明
+
+启用 `svgr` 后，`import Logo from "./logo.svg?react"` 的模块类型由
+`@hzab/vite-config/svg-react` 提供。该入口是纯类型入口（运行时为空模块，不导出任何
+运行时逻辑），声明 `*.svg?react` 默认导出 `FunctionComponent<SVGProps<SVGSVGElement>>`；
+普通 `*.svg` 仍走 Vite 默认 URL 类型。消费方任选一种方式引用：
+
+```ts
+// 方式一：tsconfig `compilerOptions.types` 数组
+// "types": ["node", "@hzab/vite-config/svg-react", ...]
+```
+
+```ts
+// 方式二：任意 .ts/.tsx 文件顶部三斜线引用
+/// <reference types="@hzab/vite-config/svg-react" />
+```
+
+```ts
+// 方式三：副作用导入（与方式一/二等价，仅加载类型声明）
+import "@hzab/vite-config/svg-react";
+```
+
+### 组件库 Vite
+
+```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",
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+    externals: [...DEFAULT_LIBRARY_EXTERNALS, "antd"],
+  }),
+);
+```
+
+`vite build` 默认产出 UMD `lib/index.js`，外置 `react` / `react-dom`；`vite` 开发为预览应用，
+不启用 lib / externals / Hash。不默认 `example/` 预览目录或 antd / Formily。详见
+[createLibraryViteConfig](./docs/api.md#createlibraryviteconfigoptions)。
+
+### 包 Vitest
+
+```ts
+import path from "node:path";
+import { defineConfig } from "vitest/config";
+import { createPackageVitestConfig } from "@hzab/vite-config/vitest";
+
+export default defineConfig(
+  createPackageVitestConfig({
+    packageRoot: __dirname,
+    react: true,
+    stubLess: true,
+    alias: {
+      "@hzab/utils": path.resolve(__dirname, "../utils/src/index.ts"),
+      "@hzab/utils/src": path.resolve(__dirname, "../utils/src"),
+    },
+    include: ["test/**/*.{test.ts,test.tsx}"],
+  }),
+);
+```
+
+Vitest 工厂及其类型仅由 `@hzab/vite-config/vitest` 导出；根入口不引用 `vitest`，仅使用
+应用 Vite 工厂时无需安装 Vitest。工厂默认 `environment: "happy-dom"`（可选 peer，使用默认
+环境需另装 `happy-dom`）；纯逻辑包可传 `environment: "node"`。启用 `stubLess` 后，普通
+Less 导入为空模块，CSS Modules 默认导入为 identity stub（如 `styles.foo === "foo"`）。
+
+## 自定义合并顺序
+
+`base(options) → mergeConfig(base, vite) → configure(final)`，之后工厂写入
+`import.meta.env.PUBLIC_PATH`（覆盖同名 `define`）。
+
+详见 [docs/](./docs/README.md)。