vite-plugin-refresh-guard 0.1.3 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/dist/{checker-gSSR0d-T.d.ts → core/checker.d.ts} +2 -5
- package/dist/{types-DaLsj7ZU.d.ts → core/types.d.ts} +11 -7
- package/dist/index.d.ts +14 -6
- package/dist/index.js +31 -1
- package/dist/react/UpdatePrompt.d.ts +3 -7
- package/dist/react/useVersionCheck.d.ts +4 -7
- package/dist/vue/useVersionCheck.d.ts +6 -10
- package/package.json +16 -13
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# 更新日志
|
|
2
2
|
|
|
3
|
+
## v0.2.0 (2026-08-13)
|
|
4
|
+
|
|
5
|
+
**dev 下改 CHANGELOG.md 即时热更新**:此前虚拟模块 `virtual:refresh-guard-changelog` 的内容在 dev server 启动时缓存,改了 CHANGELOG 必须重启 vite 才生效——在真实项目里踩到(改了日志以为没生效,重启才发现)。
|
|
6
|
+
|
|
7
|
+
- 插件 `load()` 里对 changelog 文件调 `this.addWatchFile()` 声明依赖(root 外的 changelog 也强制监听)
|
|
8
|
+
- 新增 `hotUpdate`(Vite 6-8 per-environment 钩子)与 `handleHotUpdate`(Vite 4-5 兼容)两个钩子:CHANGELOG 变化时 invalidate 虚拟模块并返回它,走 Vite 默认 js-update 推给 importers——页面不用重启,更新日志自动刷新
|
|
9
|
+
- `readChangelog` 导出并补单测(版本号解析 / 正文截取 / 日期行剔除 / `false` 关闭 / 文件缺失兜底),此前该函数零覆盖
|
|
10
|
+
|
|
11
|
+
## v0.1.4 (2026-08-11)
|
|
12
|
+
|
|
13
|
+
修复自 v0.1.1(甚至更早)起就存在的发布产物残缺问题:`tsconfig.build.json`(构建脚本 `tsc -p tsconfig.build.json` 这一步依赖的配置文件)一直没有提交进 git,导致:
|
|
14
|
+
|
|
15
|
+
- **GitHub CI 一直是红的**(`npm run build` 在干净 checkout 下找不到这个配置文件而失败),只是发布本身走的是本地手动 `npm publish`,没人注意到。
|
|
16
|
+
- **本地 `npm run build` 因为工作目录里残留着这个未提交的文件而"看起来是好的"**,掩盖了问题。
|
|
17
|
+
- **发布到 npm 的产物里缺失 `dist/core/types.d.ts`、`dist/core/checker.d.ts`**:`dist/vue/UpdatePrompt.vue`、`dist/react/UpdatePrompt.d.ts` 里 `import type { UpdateMode } from '../core/types'` 这个相对路径解析不到目标文件,导致所有消费方用 `vue-tsc`/`tsc` 类型检查时报 `TS2307: Cannot find module '../core/types'`(在两个真实项目 hym-admin、mzmeso-manager 里复现并确认)。
|
|
18
|
+
|
|
19
|
+
这版把 `tsconfig.build.json` 提交进 git,`npm run compat`(typecheck + test + build)全部通过,构建产物里 `dist/core/*.d.ts` 正确生成。
|
|
20
|
+
|
|
3
21
|
## v0.1.3 (2026-08-09)
|
|
4
22
|
|
|
5
23
|
`UpdatePrompt` 默认样式全部改成 `var(--rg-*, 默认值)` 的写法,颜色/圆角都能被外部 CSS 变量覆盖,不用改包源码就能换成自己的品牌色(README 新增"样式定制"一节说明全部变量)。默认样式本身也精修了一版(更大的圆角、更细腻的阴影分层、按钮 hover/active 反馈、标题加了个 ✨),不设置任何变量也比之前顺眼。
|
|
@@ -1,11 +1,10 @@
|
|
|
1
|
-
import {
|
|
2
|
-
|
|
1
|
+
import type { UpdateEvent, UpdateListener, VersionCheckerOptions, VersionInfo } from './types';
|
|
3
2
|
/**
|
|
4
3
|
* Framework-agnostic engine: polls (or is told about) a new version, decides whether to refresh
|
|
5
4
|
* based on `mode`, and guards against reload loops / stale-chunk white-screens. Vue/React
|
|
6
5
|
* adapters are thin wrappers around this — use it directly if you're on something else.
|
|
7
6
|
*/
|
|
8
|
-
declare class UpdateChecker {
|
|
7
|
+
export declare class UpdateChecker {
|
|
9
8
|
private opts;
|
|
10
9
|
private currentVersion;
|
|
11
10
|
private timer;
|
|
@@ -34,5 +33,3 @@ declare class UpdateChecker {
|
|
|
34
33
|
on(event: UpdateEvent, listener: UpdateListener): () => void;
|
|
35
34
|
private emit;
|
|
36
35
|
}
|
|
37
|
-
|
|
38
|
-
export { UpdateChecker as U };
|
|
@@ -1,11 +1,17 @@
|
|
|
1
|
-
type UpdateMode = 'silent' | 'toast-auto' | 'modal-blocking';
|
|
2
|
-
interface VersionInfo {
|
|
1
|
+
export type UpdateMode = 'silent' | 'toast-auto' | 'modal-blocking';
|
|
2
|
+
export interface VersionInfo {
|
|
3
3
|
version: string;
|
|
4
4
|
buildId?: string;
|
|
5
5
|
commit?: string;
|
|
6
6
|
time?: string;
|
|
7
7
|
}
|
|
8
|
-
interface
|
|
8
|
+
export interface ChangelogInfo {
|
|
9
|
+
/** Latest version heading found in the changelog, e.g. "v1.5.0" */
|
|
10
|
+
version: string;
|
|
11
|
+
/** Rendered body for that version's section (markdown, unprocessed) */
|
|
12
|
+
content: string;
|
|
13
|
+
}
|
|
14
|
+
export interface VersionCheckerOptions {
|
|
9
15
|
/** Where to fetch version info from. Default: '/version.json' (see the Vite plugin, which emits this file at build time). */
|
|
10
16
|
versionUrl?: string;
|
|
11
17
|
/** Poll interval in ms. Default: 5 minutes. Set to 0 to disable polling (e.g. if you only drive checks from a service-worker hook). */
|
|
@@ -42,7 +48,5 @@ interface VersionCheckerOptions {
|
|
|
42
48
|
/** Called immediately before the actual page refresh happens (any mode). Good place to flush analytics, etc. */
|
|
43
49
|
onBeforeRefresh?: () => void;
|
|
44
50
|
}
|
|
45
|
-
type UpdateEvent = 'update-available' | 'refreshing';
|
|
46
|
-
type UpdateListener = (info: VersionInfo | null) => void;
|
|
47
|
-
|
|
48
|
-
export type { UpdateMode as U, VersionCheckerOptions as V, VersionInfo as a, UpdateEvent as b, UpdateListener as c };
|
|
51
|
+
export type UpdateEvent = 'update-available' | 'refreshing';
|
|
52
|
+
export type UpdateListener = (info: VersionInfo | null) => void;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,5 @@
|
|
|
1
|
-
import { Plugin } from 'vite';
|
|
2
|
-
|
|
3
|
-
interface RefreshGuardPluginOptions {
|
|
1
|
+
import type { Plugin } from 'vite';
|
|
2
|
+
export interface RefreshGuardPluginOptions {
|
|
4
3
|
/** Version string to bake into version.json and the `__REFRESH_GUARD_VERSION__` define. Default: read from the project's package.json. */
|
|
5
4
|
version?: string;
|
|
6
5
|
/** Include the short git commit hash in version.json. Default: true — silently omitted outside a git repo (e.g. a tarball deploy), never throws. */
|
|
@@ -13,6 +12,16 @@ interface RefreshGuardPluginOptions {
|
|
|
13
12
|
*/
|
|
14
13
|
changelog?: string | false;
|
|
15
14
|
}
|
|
15
|
+
/**
|
|
16
|
+
* 读取 CHANGELOG 最新版本的版本号与正文(导出供测试复用;接入方不需要直接用)。
|
|
17
|
+
*/
|
|
18
|
+
export declare function readChangelog(root: string, changelogOption: string | false | undefined): {
|
|
19
|
+
latestVersion: null;
|
|
20
|
+
latestContent: string;
|
|
21
|
+
} | {
|
|
22
|
+
latestVersion: string;
|
|
23
|
+
latestContent: string;
|
|
24
|
+
};
|
|
16
25
|
/**
|
|
17
26
|
* Vite plugin half of refresh-guard: bakes the current build's version into your bundle
|
|
18
27
|
* (as `__REFRESH_GUARD_VERSION__`) and emits a `version.json` manifest that the runtime
|
|
@@ -22,6 +31,5 @@ interface RefreshGuardPluginOptions {
|
|
|
22
31
|
* since HMR already covers that case; point a static-file server or `vite preview` at the
|
|
23
32
|
* build output to see it end to end.
|
|
24
33
|
*/
|
|
25
|
-
declare function refreshGuard(options?: RefreshGuardPluginOptions): Plugin;
|
|
26
|
-
|
|
27
|
-
export { type RefreshGuardPluginOptions, refreshGuard as default, refreshGuard };
|
|
34
|
+
export declare function refreshGuard(options?: RefreshGuardPluginOptions): Plugin;
|
|
35
|
+
export default refreshGuard;
|
package/dist/index.js
CHANGED
|
@@ -12,7 +12,7 @@ function readChangelog(root, changelogOption) {
|
|
|
12
12
|
const heading = md.match(/^##\s+(v?[\d.]+)/m);
|
|
13
13
|
if (!heading) return { latestVersion: null, latestContent: "" };
|
|
14
14
|
const sections = md.split(/^## /m);
|
|
15
|
-
const body = sections.length > 1 ? sections[1].replace(/^v?[\d.]+\s
|
|
15
|
+
const body = sections.length > 1 ? sections[1].replace(/^v?[\d.]+\s*(?:\(.*?\))?\s*\n?/, "").trim() : "";
|
|
16
16
|
return { latestVersion: heading[1], latestContent: body };
|
|
17
17
|
}
|
|
18
18
|
function refreshGuard(options = {}) {
|
|
@@ -20,6 +20,7 @@ function refreshGuard(options = {}) {
|
|
|
20
20
|
let version = options.version;
|
|
21
21
|
const buildId = String(Date.now());
|
|
22
22
|
let commit = "";
|
|
23
|
+
let changelogPath = "";
|
|
23
24
|
return {
|
|
24
25
|
name: "vite-plugin-refresh-guard",
|
|
25
26
|
// `config()` runs before `configResolved()` — the version has to be settled here, not there,
|
|
@@ -39,6 +40,7 @@ function refreshGuard(options = {}) {
|
|
|
39
40
|
},
|
|
40
41
|
configResolved(resolvedConfig) {
|
|
41
42
|
config = resolvedConfig;
|
|
43
|
+
changelogPath = options.changelog === false ? "" : resolve(config.root, options.changelog || "CHANGELOG.md");
|
|
42
44
|
if (options.includeCommit !== false) {
|
|
43
45
|
try {
|
|
44
46
|
commit = execSync("git rev-parse --short HEAD", { cwd: config.root, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
|
|
@@ -52,11 +54,38 @@ function refreshGuard(options = {}) {
|
|
|
52
54
|
},
|
|
53
55
|
load(id) {
|
|
54
56
|
if (id !== RESOLVED_VIRTUAL_ID) return;
|
|
57
|
+
if (changelogPath) this.addWatchFile(changelogPath);
|
|
55
58
|
const { latestVersion, latestContent } = readChangelog(config.root, options.changelog);
|
|
56
59
|
return `export const latestVersion = ${JSON.stringify(latestVersion)};
|
|
57
60
|
export const latestContent = ${JSON.stringify(latestContent)};
|
|
58
61
|
`;
|
|
59
62
|
},
|
|
63
|
+
/**
|
|
64
|
+
* dev 下 CHANGELOG.md 变化 → invalidate 虚拟模块并返回它,让 Vite 走默认 updateModules
|
|
65
|
+
* 给 importers 推 js-update,页面不用重启就能拿到最新更新日志。
|
|
66
|
+
*
|
|
67
|
+
* 兼容 Vite 4-8:Vite 6+ 用 per-environment `hotUpdate`(environment 在 this.environment,
|
|
68
|
+
* 触发文件在 options.file);Vite 4-5 用旧版 `handleHotUpdate(ctx)`(ctx.file + ctx.server.moduleGraph)。
|
|
69
|
+
* 两个钩子都实现,各自能跑到的版本走各自的,跑不到的会被 Vite 忽略。
|
|
70
|
+
*/
|
|
71
|
+
hotUpdate(options2) {
|
|
72
|
+
if (!changelogPath) return;
|
|
73
|
+
const mod = this.environment.moduleGraph?.getModuleById(RESOLVED_VIRTUAL_ID);
|
|
74
|
+
if (options2.file === changelogPath && mod) {
|
|
75
|
+
this.environment.moduleGraph.invalidateModule(mod);
|
|
76
|
+
return [mod];
|
|
77
|
+
}
|
|
78
|
+
},
|
|
79
|
+
handleHotUpdate(ctx) {
|
|
80
|
+
if (!changelogPath) return;
|
|
81
|
+
if (ctx.file !== changelogPath) return;
|
|
82
|
+
const graph = ctx.server.moduleGraph;
|
|
83
|
+
const mod = graph.getModuleById(RESOLVED_VIRTUAL_ID);
|
|
84
|
+
if (mod) {
|
|
85
|
+
graph.invalidateModule(mod);
|
|
86
|
+
return [mod];
|
|
87
|
+
}
|
|
88
|
+
},
|
|
60
89
|
generateBundle() {
|
|
61
90
|
const manifest = {
|
|
62
91
|
version: version ?? "0.0.0",
|
|
@@ -75,5 +104,6 @@ export const latestContent = ${JSON.stringify(latestContent)};
|
|
|
75
104
|
var index_default = refreshGuard;
|
|
76
105
|
export {
|
|
77
106
|
index_default as default,
|
|
107
|
+
readChangelog,
|
|
78
108
|
refreshGuard
|
|
79
109
|
};
|
|
@@ -1,7 +1,5 @@
|
|
|
1
|
-
import
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
interface UpdatePromptProps {
|
|
1
|
+
import type { UpdateMode } from '../core/types';
|
|
2
|
+
export interface UpdatePromptProps {
|
|
5
3
|
visible: boolean;
|
|
6
4
|
mode?: UpdateMode;
|
|
7
5
|
/** Optional: e.g. `latestVersion` from `virtual:refresh-guard-changelog`. */
|
|
@@ -17,6 +15,4 @@ interface UpdatePromptProps {
|
|
|
17
15
|
dark?: boolean;
|
|
18
16
|
onRefresh: () => void;
|
|
19
17
|
}
|
|
20
|
-
declare function UpdatePrompt({ visible, mode, version, changelogHtml, dark, onRefresh }: UpdatePromptProps): react.ReactPortal | null;
|
|
21
|
-
|
|
22
|
-
export { UpdatePrompt, type UpdatePromptProps };
|
|
18
|
+
export declare function UpdatePrompt({ visible, mode, version, changelogHtml, dark, onRefresh }: UpdatePromptProps): import("react").ReactPortal | null;
|
|
@@ -1,21 +1,18 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
|
|
1
|
+
import { UpdateChecker } from '../core/checker';
|
|
2
|
+
import type { VersionCheckerOptions, VersionInfo } from '../core/types';
|
|
4
3
|
/**
|
|
5
4
|
* React hook wrapping the framework-agnostic UpdateChecker. Mounts/unmounts the checker with
|
|
6
5
|
* the component's lifecycle automatically.
|
|
7
6
|
*
|
|
8
7
|
* @param currentVersion Usually `__REFRESH_GUARD_VERSION__` (injected by the Vite plugin).
|
|
9
8
|
*/
|
|
10
|
-
declare function useVersionCheck(currentVersion: string, options?: VersionCheckerOptions): {
|
|
9
|
+
export declare function useVersionCheck(currentVersion: string, options?: VersionCheckerOptions): {
|
|
11
10
|
hasUpdate: boolean;
|
|
12
11
|
latestInfo: VersionInfo | null;
|
|
13
|
-
mode: UpdateMode;
|
|
12
|
+
mode: import("../core/types").UpdateMode;
|
|
14
13
|
applyUpdate: () => void;
|
|
15
14
|
checkNow: () => Promise<boolean>;
|
|
16
15
|
/** Feed a vite-plugin-pwa `onNeedRefresh` (or any other out-of-band) signal into the same mode logic. */
|
|
17
16
|
notifyExternalUpdate: (info?: VersionInfo) => void;
|
|
18
17
|
checker: UpdateChecker;
|
|
19
18
|
};
|
|
20
|
-
|
|
21
|
-
export { useVersionCheck };
|
|
@@ -1,22 +1,18 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import
|
|
3
|
-
import { U as UpdateChecker } from '../checker-gSSR0d-T.js';
|
|
4
|
-
|
|
1
|
+
import { UpdateChecker } from '../core/checker';
|
|
2
|
+
import type { VersionCheckerOptions, VersionInfo } from '../core/types';
|
|
5
3
|
/**
|
|
6
4
|
* Vue composable wrapping the framework-agnostic UpdateChecker. Mounts/unmounts the checker
|
|
7
5
|
* with the component's lifecycle automatically.
|
|
8
6
|
*
|
|
9
7
|
* @param currentVersion Usually `__REFRESH_GUARD_VERSION__` (injected by the Vite plugin).
|
|
10
8
|
*/
|
|
11
|
-
declare function useVersionCheck(currentVersion: string, options?: VersionCheckerOptions): {
|
|
12
|
-
hasUpdate: vue.Ref<boolean, boolean>;
|
|
13
|
-
latestInfo: vue.ShallowRef<VersionInfo | null, VersionInfo | null>;
|
|
14
|
-
mode: UpdateMode;
|
|
9
|
+
export declare function useVersionCheck(currentVersion: string, options?: VersionCheckerOptions): {
|
|
10
|
+
hasUpdate: import("vue").Ref<boolean, boolean>;
|
|
11
|
+
latestInfo: import("vue").ShallowRef<VersionInfo | null, VersionInfo | null>;
|
|
12
|
+
mode: import("../core/types").UpdateMode;
|
|
15
13
|
applyUpdate: () => void;
|
|
16
14
|
checkNow: () => Promise<boolean>;
|
|
17
15
|
/** Feed a vite-plugin-pwa `onNeedRefresh` (or any other out-of-band) signal into the same mode logic. */
|
|
18
16
|
notifyExternalUpdate: (info?: VersionInfo) => void;
|
|
19
17
|
checker: UpdateChecker;
|
|
20
18
|
};
|
|
21
|
-
|
|
22
|
-
export { useVersionCheck };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vite-plugin-refresh-guard",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Vite 应用的可配置版本更新检测+刷新方案:静默自动刷新 / 提示后自动刷新 / 弹窗阻断,按产品需要选档位,核心逻辑框架无关,附 Vue/React 适配层。Configurable new-version detection + refresh for Vite apps — silent / toast-auto / modal-blocking, framework-agnostic core with Vue and React adapters.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -49,7 +49,7 @@
|
|
|
49
49
|
"CHANGELOG.md"
|
|
50
50
|
],
|
|
51
51
|
"scripts": {
|
|
52
|
-
"build": "tsup src/index.ts src/vue/useVersionCheck.ts src/react/useVersionCheck.ts src/react/UpdatePrompt.tsx --format esm --
|
|
52
|
+
"build": "tsup src/index.ts src/vue/useVersionCheck.ts src/react/useVersionCheck.ts src/react/UpdatePrompt.tsx --format esm --clean && tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
|
|
53
53
|
"typecheck": "tsc --noEmit",
|
|
54
54
|
"test": "vitest run",
|
|
55
55
|
"compat": "npm run typecheck && npm test && npm run build",
|
|
@@ -58,7 +58,7 @@
|
|
|
58
58
|
"peerDependencies": {
|
|
59
59
|
"react": ">=18",
|
|
60
60
|
"react-dom": ">=18",
|
|
61
|
-
"vite": ">=4 <
|
|
61
|
+
"vite": ">=4 <10",
|
|
62
62
|
"vue": ">=3"
|
|
63
63
|
},
|
|
64
64
|
"peerDependenciesMeta": {
|
|
@@ -73,16 +73,19 @@
|
|
|
73
73
|
}
|
|
74
74
|
},
|
|
75
75
|
"devDependencies": {
|
|
76
|
-
"@types/node": "^
|
|
77
|
-
"@types/react": "^
|
|
78
|
-
"@types/react-dom": "^
|
|
76
|
+
"@types/node": "^24.10.11",
|
|
77
|
+
"@types/react": "^19.2.18",
|
|
78
|
+
"@types/react-dom": "^19.2.4",
|
|
79
79
|
"jsdom": "^30.0.1",
|
|
80
|
-
"react": "^
|
|
81
|
-
"react-dom": "^
|
|
82
|
-
"tsup": "^8.
|
|
83
|
-
"typescript": "^
|
|
84
|
-
"vite": "^
|
|
85
|
-
"vitest": "^
|
|
86
|
-
"vue": "^3.
|
|
80
|
+
"react": "^19.2.8",
|
|
81
|
+
"react-dom": "^19.2.8",
|
|
82
|
+
"tsup": "^8.5.1",
|
|
83
|
+
"typescript": "^7.0.2",
|
|
84
|
+
"vite": "^8.2.1",
|
|
85
|
+
"vitest": "^4.1.10",
|
|
86
|
+
"vue": "^3.5.41"
|
|
87
|
+
},
|
|
88
|
+
"engines": {
|
|
89
|
+
"node": ">=20.19"
|
|
87
90
|
}
|
|
88
91
|
}
|