From 8c94b853a44f4ddd57eda43b6b25eeb36b79402a Mon Sep 17 00:00:00 2001 From: Utopia Date: Mon, 22 Jun 2026 13:47:37 +0800 Subject: [PATCH 01/10] docs: add nuxt support design spec Co-Authored-By: Claude Opus 4.8 --- .../specs/2026-06-22-nuxt-support-design.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-22-nuxt-support-design.md diff --git a/docs/superpowers/specs/2026-06-22-nuxt-support-design.md b/docs/superpowers/specs/2026-06-22-nuxt-support-design.md new file mode 100644 index 0000000..2e95048 --- /dev/null +++ b/docs/superpowers/specs/2026-06-22-nuxt-support-design.md @@ -0,0 +1,88 @@ +# 设计:`@plugin-web-update-notification/nuxt` + +- 日期:2026-06-22 +- 状态:已确认,待实现 +- 范围:核心 module 包 + 文档/README(不含 example、测试) + +## 背景与目标 + +为 plugin-web-update-notification 增加 Nuxt 支持,使 Nuxt 项目能像 Vite/Umi/Webpack/Rspack 一样检测网页更新并通知用户刷新。 + +核心原理不变:构建时把版本号写入 `version.json`,注入检测脚本与样式,客户端轮询服务器版本号并与本地比较,不同则通知刷新。 + +### 硬需求 + +- **覆盖全部部署模式**:SSG(`nuxt generate`)、SPA(`ssr: false`)、SSR(`nuxt build` + 运行时渲染)。 +- **仅支持 Nuxt 3+(含 Nuxt 4)**,不兼容 Nuxt 2 / Bridge。 + +## 架构决策 + +新建独立子包 `@plugin-web-update-notification/nuxt`,以标准 **Nuxt Module**(`defineNuxtModule`)实现,复用 `@plugin-web-update-notification/core` 的全部核心能力。 + +### 为什么不复用 vite 插件 + +现有 `@plugin-web-update-notification/vite` 依赖 Vite 的 `apply:'build'` + `transformIndexHtml` + `generateBundle`。在 Nuxt **SSR 模式下这些钩子不参与 Nitro 的 HTML 渲染与资源产出**,HTML 由 Nitro 在运行时渲染、静态资源由 Nitro 产出,因此无法满足「全模式」要求。SSG 下也容易与 Nuxt 的 HTML 处理冲突。 + +被否决的替代方案: + +- **方案 B(仅文档教用户把 vite 插件塞进 `nuxt.config.vite.plugins`)**:SSR 下根本不触发,排除。 +- **方案 C(在 vite 包内加 `/nuxt` 子入口)**:职责混杂、引入 `@nuxt/kit` 依赖,且与仓库「一框架一包」(umijs/webpack/rspack 各自独立)的结构不一致,排除。 + +## 包结构 + +``` +packages/nuxt/ + package.json # name: @plugin-web-update-notification/nuxt + tsdown.config.ts # 与其他包一致,tsdown 构建 ESM + src/ + index.ts # defineNuxtModule 主体 + README.md +``` + +- `dependencies`: `@plugin-web-update-notification/core: workspace:*` +- `peerDependencies`: `nuxt: ^3.0.0 || ^4.0.0` +- `devDependencies`: `@nuxt/kit`、`nuxt` +- 构建产物:`dist/index.mjs` + `dist/index.d.mts`(ESM,Nuxt module 标准形态),`exports` 字段与 vite 包对齐 +- turbo / pnpm workspace 自动纳入 `pnpm build`、`pnpm typecheck` + +## 运行机制(复用 core,三模式统一) + +模块 `setup(options, nuxt)` 流程: + +1. **仅生产构建生效**:`if (nuxt.options.dev) return`(对应 vite 的 `apply:'build'`、umi 的 `api.env === 'production'`)。 +2. **取版本号**:复用 core 的 `getVersion(versionType, customVersion)`,逻辑与 vite/umi 一致;取不到则提前返回。 +3. **生成注入内容**:用 `get__Dirname()` 从 core dist 读取 `inject.js` / `inject.css` 源码,`generateJsFileContent` 生成脚本,`getFileHash` 算出 `jsFileHash` / `cssFileHash`(与现有包同一套常量与函数)。 +4. **`injectFileBase` 默认值**:取 `nuxt.options.app.baseURL`(Nuxt 中对应 vite 的 `base` / umi 的 `publicPath`),用户可显式覆盖。 +5. **注入 head 标签**(unhead,三模式都生效): + - 往 `nuxt.options.app.head.script` 推 `