vite-plugin-refresh-guard 0.1.0 → 0.1.2
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 +24 -8
- package/README.en.md +171 -0
- package/README.md +67 -61
- package/dist/react/UpdatePrompt.d.ts +8 -1
- package/dist/react/UpdatePrompt.js +5 -3
- package/dist/vue/UpdatePrompt.vue +14 -3
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,12 +1,28 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 更新日志
|
|
2
|
+
|
|
3
|
+
## v0.1.2 (2026-08-09)
|
|
4
|
+
|
|
5
|
+
修 `UpdatePrompt` 两个实测踩到的问题(在一个真实项目里第一次接入后暴露的):
|
|
6
|
+
|
|
7
|
+
- **弹窗只显示 git hash,看不出更新了什么**:`modal-blocking` 弹窗现在建议配合 `changelog-html`
|
|
8
|
+
prop 传入 `virtual:refresh-guard-changelog` 的内容——之前这个 prop 就存在但接入时容易漏传,
|
|
9
|
+
这版把它在 README/SKILL.md 里的位置提得更显眼。
|
|
10
|
+
- **弹窗颜色跟着访问者系统的深色模式走,不跟着网站自己的主题开关走**:Vue/React 版都加了 `dark`
|
|
11
|
+
prop,显式传入你自己的主题状态(如 `isDark.value`)就能让弹窗配色跟着网站自己的主题走,不传
|
|
12
|
+
则维持原来的 `prefers-color-scheme` 兜底行为。
|
|
13
|
+
|
|
14
|
+
## v0.1.1 (2026-08-09)
|
|
15
|
+
|
|
16
|
+
- README 改为中文正文 + 英文版(`README.en.md`),CHANGELOG/package.json 描述同步改中文为主
|
|
17
|
+
- 源码注释保持英文不变
|
|
2
18
|
|
|
3
19
|
## v0.1.0 (2026-08-09)
|
|
4
20
|
|
|
5
|
-
|
|
21
|
+
首次发布。
|
|
6
22
|
|
|
7
|
-
- Vite
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
- Vue
|
|
11
|
-
- React hook + `UpdatePrompt`
|
|
12
|
-
- `notifyExternalUpdate()`
|
|
23
|
+
- Vite 插件:构建期产出 `version.json`,把 `__REFRESH_GUARD_VERSION__` 烘焙进 bundle,另有可选的 `virtual:refresh-guard-changelog` 虚拟模块
|
|
24
|
+
- 框架无关的 `UpdateChecker` 核心:轮询 + 标签页重新可见时检测 + 旧 chunk 加载失败兜底 + 刷新防抖冷却
|
|
25
|
+
- 三档可配置强度:`silent`、`toast-auto`(默认)、`modal-blocking`
|
|
26
|
+
- Vue 组合式函数 + `UpdatePrompt.vue`
|
|
27
|
+
- React hook + `UpdatePrompt` 组件
|
|
28
|
+
- `notifyExternalUpdate()` 逃生舱:把 `vite-plugin-pwa` 的 `onNeedRefresh` 或任何其他外部信号接进同一套档位逻辑
|
package/README.en.md
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# vite-plugin-refresh-guard
|
|
2
|
+
|
|
3
|
+
[中文](./README.md) | English
|
|
4
|
+
|
|
5
|
+
[](https://github.com/webkubor/vite-plugin-refresh-guard/actions/workflows/ci.yml)
|
|
6
|
+
[](https://www.npmjs.com/package/vite-plugin-refresh-guard)
|
|
7
|
+
[](./LICENSE)
|
|
8
|
+
[](https://vitejs.dev)
|
|
9
|
+
[](https://vuejs.org)
|
|
10
|
+
[](https://react.dev)
|
|
11
|
+
|
|
12
|
+
Configurable "there's a new version, here's what happens next" for Vite apps.
|
|
13
|
+
|
|
14
|
+
Most projects that solve this end up with one of three answers, usually picked by accident and
|
|
15
|
+
never revisited:
|
|
16
|
+
|
|
17
|
+
- **Silent** — just refresh in the background, the user never notices.
|
|
18
|
+
- **Toast, then auto-refresh** — a small non-blocking notice, then refresh after a short delay.
|
|
19
|
+
- **Blocking modal** — stop the user, make them click "update now" before they can continue.
|
|
20
|
+
|
|
21
|
+
This package makes that an explicit, per-project choice instead of copy-pasted glue code that
|
|
22
|
+
drifts every time someone touches it. Framework-agnostic core, thin Vue and React adapters.
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npm i -D vite-plugin-refresh-guard
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`vue`, `react`/`react-dom`, and `vite` are peer dependencies — install whichever you actually use.
|
|
31
|
+
|
|
32
|
+
## Quick start
|
|
33
|
+
|
|
34
|
+
**`vite.config.ts`**
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import { defineConfig } from 'vite'
|
|
38
|
+
import { refreshGuard } from 'vite-plugin-refresh-guard'
|
|
39
|
+
|
|
40
|
+
export default defineConfig({
|
|
41
|
+
plugins: [refreshGuard()],
|
|
42
|
+
})
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
This does two things at build time:
|
|
46
|
+
1. Writes `version.json` into your build output (`{ version, buildId, commit, time }`).
|
|
47
|
+
2. Bakes the current version into your bundle as a global, `__REFRESH_GUARD_VERSION__`.
|
|
48
|
+
|
|
49
|
+
**Vue**
|
|
50
|
+
|
|
51
|
+
```vue
|
|
52
|
+
<script setup lang="ts">
|
|
53
|
+
import { useVersionCheck } from 'vite-plugin-refresh-guard/vue'
|
|
54
|
+
import UpdatePrompt from 'vite-plugin-refresh-guard/vue/UpdatePrompt.vue'
|
|
55
|
+
import { latestContent } from 'virtual:refresh-guard-changelog'
|
|
56
|
+
// import { isDark } from './your-theme-state' — pass this too if your site has a theme toggle
|
|
57
|
+
|
|
58
|
+
const { hasUpdate, latestInfo, applyUpdate, mode } = useVersionCheck(__REFRESH_GUARD_VERSION__, {
|
|
59
|
+
mode: 'toast-auto', // 'silent' | 'toast-auto' | 'modal-blocking'
|
|
60
|
+
})
|
|
61
|
+
</script>
|
|
62
|
+
|
|
63
|
+
<template>
|
|
64
|
+
<UpdatePrompt
|
|
65
|
+
:visible="hasUpdate" :mode="mode" :version="latestInfo?.version"
|
|
66
|
+
:changelog-html="latestContent"
|
|
67
|
+
@refresh="applyUpdate"
|
|
68
|
+
/>
|
|
69
|
+
</template>
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
> Don't skip `:changelog-html` — without it, the `modal-blocking` prompt only shows a git hash and
|
|
73
|
+
> the user has no idea what actually changed. If your site has a dark mode, pass your theme state
|
|
74
|
+
> to `:dark` (e.g. `:dark="isDark"`) so the modal follows your site's own theme — otherwise it only
|
|
75
|
+
> follows the visitor's OS dark-mode setting, which can look broken (a light site with a dark modal).
|
|
76
|
+
|
|
77
|
+
**React**
|
|
78
|
+
|
|
79
|
+
```tsx
|
|
80
|
+
import { useVersionCheck } from 'vite-plugin-refresh-guard/react'
|
|
81
|
+
import { UpdatePrompt } from 'vite-plugin-refresh-guard/react/UpdatePrompt'
|
|
82
|
+
// import { latestContent } from 'virtual:refresh-guard-changelog' — wire this up however your React setup handles virtual modules
|
|
83
|
+
|
|
84
|
+
function App() {
|
|
85
|
+
const { hasUpdate, latestInfo, applyUpdate, mode } = useVersionCheck(__REFRESH_GUARD_VERSION__, {
|
|
86
|
+
mode: 'modal-blocking',
|
|
87
|
+
})
|
|
88
|
+
return (
|
|
89
|
+
<UpdatePrompt
|
|
90
|
+
visible={hasUpdate} mode={mode} version={latestInfo?.version}
|
|
91
|
+
changelogHtml={latestContent}
|
|
92
|
+
dark={isDarkMode /* pass your own theme state; omitting it always renders light */}
|
|
93
|
+
onRefresh={applyUpdate}
|
|
94
|
+
/>
|
|
95
|
+
)
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Add `/// <reference types="vite-plugin-refresh-guard/client" />` to your `env.d.ts` (or wherever
|
|
101
|
+
your other `vite/client` reference lives) so TypeScript knows about `__REFRESH_GUARD_VERSION__`.
|
|
102
|
+
|
|
103
|
+
Don't want the prebuilt UI? Use `useVersionCheck`'s `hasUpdate`/`latestInfo`/`applyUpdate` and
|
|
104
|
+
render your own — the components are a starting point, not a requirement.
|
|
105
|
+
|
|
106
|
+
## Picking a mode
|
|
107
|
+
|
|
108
|
+
| Mode | User sees | When to use it |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| `silent` | Nothing. Refreshes in the background. | Internal tools, dashboards nobody's mid-task in. Pairs well with `vite-plugin-pwa`'s own `registerType: 'autoUpdate'` doing the same job at the service-worker level — you may not need this package's polling at all in that case, just wire `notifyExternalUpdate()` (see below) if you want changelog display too. |
|
|
111
|
+
| `toast-auto` (default) | A small corner notice, then refresh after `autoRefreshDelay` (default 1.2s). | Most consumer-facing apps. Gives the user a beat to notice, doesn't block them. |
|
|
112
|
+
| `modal-blocking` | A centered, non-dismissible prompt. Refresh only on click. | Apps where refreshing mid-task loses real work (a half-filled form, an in-progress upload), or where you want confirmation before applying (matches what we found in ModelGo's console app). |
|
|
113
|
+
|
|
114
|
+
You're not locked into version.json polling only — `checker.notifyExternalUpdate(info)` (also
|
|
115
|
+
exposed by both adapters) feeds an update signal from anywhere else into the same mode logic,
|
|
116
|
+
most usefully from `vite-plugin-pwa`'s `registerSW({ onNeedRefresh })` callback if you're also
|
|
117
|
+
running a service worker and want its update event to drive the same toast/modal instead of
|
|
118
|
+
(or in addition to) polling.
|
|
119
|
+
|
|
120
|
+
## Options
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
interface VersionCheckerOptions {
|
|
124
|
+
versionUrl?: string // default '/version.json'
|
|
125
|
+
interval?: number // default 5 minutes; 0 disables polling
|
|
126
|
+
checkOnVisible?: boolean // re-check on tab focus, default true
|
|
127
|
+
mode?: 'silent' | 'toast-auto' | 'modal-blocking' // default 'toast-auto'
|
|
128
|
+
autoRefreshDelay?: number // toast-auto only, default 1200ms
|
|
129
|
+
refreshCooldown?: number // min ms between forced refreshes, default 90s — guards against reload loops
|
|
130
|
+
guardChunkErrors?: boolean // force-refresh once on a stale-chunk load failure, default true
|
|
131
|
+
onUpdateAvailable?: (info) => void | boolean // return false to take over the UI yourself
|
|
132
|
+
onBeforeRefresh?: () => void // flush analytics etc. right before location.reload()
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Plugin options (`refreshGuard({ ... })`):
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
interface RefreshGuardPluginOptions {
|
|
140
|
+
version?: string // default: read from package.json
|
|
141
|
+
includeCommit?: boolean // default true; silently omitted outside a git repo
|
|
142
|
+
outFile?: string // default 'version.json'
|
|
143
|
+
changelog?: string | false // default 'CHANGELOG.md'; false disables the virtual module
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Changelog display (optional, decoupled from the refresh decision)
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
import { latestVersion, latestContent } from 'virtual:refresh-guard-changelog'
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Parses `## vX.Y.Z (date)` headings (same format as Keep a Changelog / most auto-generated
|
|
154
|
+
changelogs) out of your `CHANGELOG.md` and exposes the latest section's version and markdown
|
|
155
|
+
body. This is independent of the refresh-trigger logic on purpose — showing "what's new" and
|
|
156
|
+
deciding "when do we reload" are different product decisions, and coupling them (as several
|
|
157
|
+
of the projects this package was extracted from originally did) is how you end up with two
|
|
158
|
+
mechanisms fighting each other.
|
|
159
|
+
|
|
160
|
+
## Why not just service workers?
|
|
161
|
+
|
|
162
|
+
`vite-plugin-pwa`'s `autoUpdate` mode is a perfectly good `silent` implementation if you're
|
|
163
|
+
already running a service worker — this package doesn't replace that. What it adds is: a
|
|
164
|
+
uniform way to also get a `toast-auto` or `modal-blocking` experience (which a bare service
|
|
165
|
+
worker can't give you a clean hook for without writing this exact plumbing yourself), a
|
|
166
|
+
non-PWA `version.json`-polling fallback for apps that don't want a service worker at all, and
|
|
167
|
+
the changelog-display layer. Use whichever pieces you need; they're independent.
|
|
168
|
+
|
|
169
|
+
## License
|
|
170
|
+
|
|
171
|
+
MIT
|
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# vite-plugin-refresh-guard
|
|
2
2
|
|
|
3
|
+
中文 | [English](./README.en.md)
|
|
4
|
+
|
|
3
5
|
[](https://github.com/webkubor/vite-plugin-refresh-guard/actions/workflows/ci.yml)
|
|
4
6
|
[](https://www.npmjs.com/package/vite-plugin-refresh-guard)
|
|
5
7
|
[](./LICENSE)
|
|
@@ -7,27 +9,25 @@
|
|
|
7
9
|
[](https://vuejs.org)
|
|
8
10
|
[](https://react.dev)
|
|
9
11
|
|
|
10
|
-
|
|
12
|
+
给 Vite 项目做"部署了新版本,接下来怎么办"的可配置方案。
|
|
11
13
|
|
|
12
|
-
|
|
13
|
-
never revisited:
|
|
14
|
+
大多数项目最后都会落在这三种答案里的一种,而且往往是随手写的、后来再也没人回头审视过:
|
|
14
15
|
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
16
|
+
- **静默**——后台自动刷新,用户完全无感
|
|
17
|
+
- **提示+自动刷新**——弹个小提示,短暂延迟后自动刷新
|
|
18
|
+
- **强制弹窗**——拦住用户,必须点"立即更新"才能继续用
|
|
18
19
|
|
|
19
|
-
|
|
20
|
-
drifts every time someone touches it. Framework-agnostic core, thin Vue and React adapters.
|
|
20
|
+
这个包把这个选择显式化、可配置化,而不是散落在各项目里、每次改动都会跑偏的胶水代码。核心逻辑跟框架无关,Vue 和 React 各有一层薄适配。
|
|
21
21
|
|
|
22
|
-
##
|
|
22
|
+
## 安装
|
|
23
23
|
|
|
24
24
|
```bash
|
|
25
25
|
npm i -D vite-plugin-refresh-guard
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
`vue
|
|
28
|
+
`vue`、`react`/`react-dom`、`vite` 都是 peerDependency——用哪个装哪个。
|
|
29
29
|
|
|
30
|
-
##
|
|
30
|
+
## 快速开始
|
|
31
31
|
|
|
32
32
|
**`vite.config.ts`**
|
|
33
33
|
|
|
@@ -40,9 +40,9 @@ export default defineConfig({
|
|
|
40
40
|
})
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
|
|
44
|
-
1.
|
|
45
|
-
2.
|
|
43
|
+
这一步在构建期做两件事:
|
|
44
|
+
1. 往构建产物里写一个 `version.json`(`{ version, buildId, commit, time }`)
|
|
45
|
+
2. 把当前版本号烘焙进 bundle,成为全局常量 `__REFRESH_GUARD_VERSION__`
|
|
46
46
|
|
|
47
47
|
**Vue**
|
|
48
48
|
|
|
@@ -50,6 +50,8 @@ This does two things at build time:
|
|
|
50
50
|
<script setup lang="ts">
|
|
51
51
|
import { useVersionCheck } from 'vite-plugin-refresh-guard/vue'
|
|
52
52
|
import UpdatePrompt from 'vite-plugin-refresh-guard/vue/UpdatePrompt.vue'
|
|
53
|
+
import { latestContent } from 'virtual:refresh-guard-changelog'
|
|
54
|
+
// import { isDark } from './your-theme-state' —— 有主题切换的话把这个也传进去
|
|
53
55
|
|
|
54
56
|
const { hasUpdate, latestInfo, applyUpdate, mode } = useVersionCheck(__REFRESH_GUARD_VERSION__, {
|
|
55
57
|
mode: 'toast-auto', // 'silent' | 'toast-auto' | 'modal-blocking'
|
|
@@ -57,92 +59,96 @@ const { hasUpdate, latestInfo, applyUpdate, mode } = useVersionCheck(__REFRESH_G
|
|
|
57
59
|
</script>
|
|
58
60
|
|
|
59
61
|
<template>
|
|
60
|
-
<UpdatePrompt
|
|
62
|
+
<UpdatePrompt
|
|
63
|
+
:visible="hasUpdate" :mode="mode" :version="latestInfo?.version"
|
|
64
|
+
:changelog-html="latestContent"
|
|
65
|
+
@refresh="applyUpdate"
|
|
66
|
+
/>
|
|
61
67
|
</template>
|
|
62
68
|
```
|
|
63
69
|
|
|
70
|
+
> `:changelog-html` 别漏了——不传的话 `modal-blocking` 弹窗只会显示一个 git hash,用户不知道更新了什么。
|
|
71
|
+
> 站点自己有深色模式的话,把主题状态传给 `:dark`(比如 `:dark="isDark"`),弹窗才会跟着网站主题走,
|
|
72
|
+
> 不然默认只跟着访问者系统的深色模式走,容易出现"网站是浅色、弹窗却是暗的"这种违和场面。
|
|
73
|
+
|
|
64
74
|
**React**
|
|
65
75
|
|
|
66
76
|
```tsx
|
|
67
77
|
import { useVersionCheck } from 'vite-plugin-refresh-guard/react'
|
|
68
78
|
import { UpdatePrompt } from 'vite-plugin-refresh-guard/react/UpdatePrompt'
|
|
79
|
+
// import { latestContent } from 'virtual:refresh-guard-changelog' —— React 项目按各自 loader 处理虚拟模块的方式引入
|
|
69
80
|
|
|
70
81
|
function App() {
|
|
71
82
|
const { hasUpdate, latestInfo, applyUpdate, mode } = useVersionCheck(__REFRESH_GUARD_VERSION__, {
|
|
72
83
|
mode: 'modal-blocking',
|
|
73
84
|
})
|
|
74
|
-
return
|
|
85
|
+
return (
|
|
86
|
+
<UpdatePrompt
|
|
87
|
+
visible={hasUpdate} mode={mode} version={latestInfo?.version}
|
|
88
|
+
changelogHtml={latestContent}
|
|
89
|
+
dark={isDarkMode /* 传你自己的主题状态,不传则始终按浅色渲染 */}
|
|
90
|
+
onRefresh={applyUpdate}
|
|
91
|
+
/>
|
|
92
|
+
)
|
|
75
93
|
}
|
|
76
94
|
```
|
|
77
95
|
|
|
78
|
-
|
|
79
|
-
|
|
96
|
+
在 `env.d.ts`(或者你放 `vite/client` reference 的地方)加一行:
|
|
97
|
+
```ts
|
|
98
|
+
/// <reference types="vite-plugin-refresh-guard/client" />
|
|
99
|
+
```
|
|
100
|
+
不然 TypeScript 不认识 `__REFRESH_GUARD_VERSION__`。
|
|
80
101
|
|
|
81
|
-
|
|
82
|
-
render your own — the components are a starting point, not a requirement.
|
|
102
|
+
不想用现成 UI?直接用 `useVersionCheck` 返回的 `hasUpdate`/`latestInfo`/`applyUpdate` 自己渲染——预置组件只是个起点,不是必须用它。
|
|
83
103
|
|
|
84
|
-
##
|
|
104
|
+
## 怎么选档位
|
|
85
105
|
|
|
86
|
-
|
|
|
106
|
+
| 档位 | 用户看到什么 | 什么时候用 |
|
|
87
107
|
|---|---|---|
|
|
88
|
-
| `silent` |
|
|
89
|
-
| `toast-auto
|
|
90
|
-
| `modal-blocking` |
|
|
108
|
+
| `silent` | 什么都看不到,后台自动刷新 | 内部工具、没人会"做到一半"的看板类页面。如果项目已经在用 `vite-plugin-pwa` 的 `registerType:'autoUpdate'`,同一件事它在 SW 层已经做了,这种情况下你可能根本不需要本包的轮询,只想要 changelog 展示的话接 `notifyExternalUpdate()`(见下文)就够 |
|
|
109
|
+
| `toast-auto`(默认) | 角落小提示,`autoRefreshDelay`(默认1.2秒)后自动刷新 | 大多数 to-C 产品。给用户一个心理准备,但不打断 |
|
|
110
|
+
| `modal-blocking` | 居中弹窗,不可点遮罩关闭,点了才刷新 | 刷新会丢失用户没保存的东西(表单填一半、正在上传),或者想要用户明确确认才应用更新的场景 |
|
|
91
111
|
|
|
92
|
-
|
|
93
|
-
exposed by both adapters) feeds an update signal from anywhere else into the same mode logic,
|
|
94
|
-
most usefully from `vite-plugin-pwa`'s `registerSW({ onNeedRefresh })` callback if you're also
|
|
95
|
-
running a service worker and want its update event to drive the same toast/modal instead of
|
|
96
|
-
(or in addition to) polling.
|
|
112
|
+
不是只能靠轮询 version.json——`checker.notifyExternalUpdate(info)`(两个框架适配层都暴露了这个方法)可以把任何来源的更新信号接进同一套档位逻辑,最常见的用法是接 `vite-plugin-pwa` 的 `registerSW({ onNeedRefresh })` 回调,如果你本来就在跑 service worker,想让它的更新事件也走同一套 toast/弹窗,而不是(或者加上)轮询。
|
|
97
113
|
|
|
98
|
-
##
|
|
114
|
+
## 配置项
|
|
99
115
|
|
|
100
116
|
```ts
|
|
101
117
|
interface VersionCheckerOptions {
|
|
102
|
-
versionUrl?: string //
|
|
103
|
-
interval?: number //
|
|
104
|
-
checkOnVisible?: boolean //
|
|
105
|
-
mode?: 'silent' | 'toast-auto' | 'modal-blocking' //
|
|
106
|
-
autoRefreshDelay?: number // toast-auto
|
|
107
|
-
refreshCooldown?: number //
|
|
108
|
-
guardChunkErrors?: boolean //
|
|
109
|
-
onUpdateAvailable?: (info) => void | boolean //
|
|
110
|
-
onBeforeRefresh?: () => void //
|
|
118
|
+
versionUrl?: string // 默认 '/version.json'
|
|
119
|
+
interval?: number // 默认 5 分钟;设 0 关闭轮询
|
|
120
|
+
checkOnVisible?: boolean // 标签页重新可见时也查一次,默认 true
|
|
121
|
+
mode?: 'silent' | 'toast-auto' | 'modal-blocking' // 默认 'toast-auto'
|
|
122
|
+
autoRefreshDelay?: number // 仅 toast-auto 用,默认 1200ms
|
|
123
|
+
refreshCooldown?: number // 两次强制刷新之间的最短间隔,默认 90 秒——防止刷新死循环
|
|
124
|
+
guardChunkErrors?: boolean // 旧 chunk 加载失败时强刷一次,默认 true
|
|
125
|
+
onUpdateAvailable?: (info) => void | boolean // 返回 false 可以自己接管 UI
|
|
126
|
+
onBeforeRefresh?: () => void // 真正 location.reload() 前调用,适合在这里补埋点
|
|
111
127
|
}
|
|
112
128
|
```
|
|
113
129
|
|
|
114
|
-
|
|
130
|
+
插件配置(`refreshGuard({ ... })`):
|
|
115
131
|
|
|
116
132
|
```ts
|
|
117
133
|
interface RefreshGuardPluginOptions {
|
|
118
|
-
version?: string //
|
|
119
|
-
includeCommit?: boolean //
|
|
120
|
-
outFile?: string //
|
|
121
|
-
changelog?: string | false //
|
|
134
|
+
version?: string // 默认读 package.json
|
|
135
|
+
includeCommit?: boolean // 默认 true;非 git 仓库时静默省略,不报错
|
|
136
|
+
outFile?: string // 默认 'version.json'
|
|
137
|
+
changelog?: string | false // 默认 'CHANGELOG.md';false 关闭虚拟模块
|
|
122
138
|
}
|
|
123
139
|
```
|
|
124
140
|
|
|
125
|
-
##
|
|
141
|
+
## 更新日志展示(可选,跟"要不要刷新"这个决定解耦)
|
|
126
142
|
|
|
127
143
|
```ts
|
|
128
144
|
import { latestVersion, latestContent } from 'virtual:refresh-guard-changelog'
|
|
129
145
|
```
|
|
130
146
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
mechanisms fighting each other.
|
|
137
|
-
|
|
138
|
-
## Why not just service workers?
|
|
139
|
-
|
|
140
|
-
`vite-plugin-pwa`'s `autoUpdate` mode is a perfectly good `silent` implementation if you're
|
|
141
|
-
already running a service worker — this package doesn't replace that. What it adds is: a
|
|
142
|
-
uniform way to also get a `toast-auto` or `modal-blocking` experience (which a bare service
|
|
143
|
-
worker can't give you a clean hook for without writing this exact plumbing yourself), a
|
|
144
|
-
non-PWA `version.json`-polling fallback for apps that don't want a service worker at all, and
|
|
145
|
-
the changelog-display layer. Use whichever pieces you need; they're independent.
|
|
147
|
+
从你的 `CHANGELOG.md` 里解析 `## vX.Y.Z (date)` 这种格式的标题(跟 Keep a Changelog 及大多数自动生成的更新日志一致),暴露最新一条的版本号和 markdown 正文。这个功能故意跟"什么时候刷新"的逻辑解耦——"展示更新了什么"和"什么时候该刷新"是两个不同的产品决策,本包最初就是从几个把这两件事强行绑死在一起的项目里抽出来的,绑死的下场就是两套机制互相打架。
|
|
148
|
+
|
|
149
|
+
## 为什么不干脆只用 service worker
|
|
150
|
+
|
|
151
|
+
如果你已经在跑 service worker,`vite-plugin-pwa` 的 `autoUpdate` 模式本身就是一个很好的 `silent` 实现——本包不是要替代它。本包补的是:一套统一的方式,能拿到 `toast-auto` 或 `modal-blocking` 的体验(裸 service worker 想要这个得自己手写这整套管线);一个不需要 service worker 的、纯靠轮询 `version.json` 的兜底方案;以及独立的更新日志展示层。哪块需要用哪块,互相不绑定。
|
|
146
152
|
|
|
147
153
|
## License
|
|
148
154
|
|
|
@@ -8,8 +8,15 @@ interface UpdatePromptProps {
|
|
|
8
8
|
version?: string | null;
|
|
9
9
|
/** Optional: e.g. `latestContent` from `virtual:refresh-guard-changelog`, rendered via dangerouslySetInnerHTML — pre-sanitize if it isn't your own trusted file. */
|
|
10
10
|
changelogHtml?: string;
|
|
11
|
+
/**
|
|
12
|
+
* Explicitly light/dark instead of always rendering light. Pass your app's own theme state
|
|
13
|
+
* here (e.g. a `useDarkMode()` hook's value) so this modal matches your site's actual theme
|
|
14
|
+
* toggle. Inline styles can't follow the OS `prefers-color-scheme` on their own, so leaving
|
|
15
|
+
* this unset always renders light — pass it explicitly if your app supports dark mode.
|
|
16
|
+
*/
|
|
17
|
+
dark?: boolean;
|
|
11
18
|
onRefresh: () => void;
|
|
12
19
|
}
|
|
13
|
-
declare function UpdatePrompt({ visible, mode, version, changelogHtml, onRefresh }: UpdatePromptProps): react.ReactPortal | null;
|
|
20
|
+
declare function UpdatePrompt({ visible, mode, version, changelogHtml, dark, onRefresh }: UpdatePromptProps): react.ReactPortal | null;
|
|
14
21
|
|
|
15
22
|
export { UpdatePrompt, type UpdatePromptProps };
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// src/react/UpdatePrompt.tsx
|
|
2
2
|
import { createPortal } from "react-dom";
|
|
3
3
|
import { jsx, jsxs } from "react/jsx-runtime";
|
|
4
|
-
function UpdatePrompt({ visible, mode = "toast-auto", version = null, changelogHtml = "", onRefresh }) {
|
|
4
|
+
function UpdatePrompt({ visible, mode = "toast-auto", version = null, changelogHtml = "", dark = false, onRefresh }) {
|
|
5
5
|
if (!visible || mode === "silent" || typeof document === "undefined") return null;
|
|
6
6
|
if (mode === "toast-auto") {
|
|
7
7
|
return createPortal(
|
|
@@ -16,13 +16,15 @@ function UpdatePrompt({ visible, mode = "toast-auto", version = null, changelogH
|
|
|
16
16
|
document.body
|
|
17
17
|
);
|
|
18
18
|
}
|
|
19
|
+
const modalStyle = dark ? { ...styles.modal, ...styles.modalDark } : styles.modal;
|
|
20
|
+
const bodyStyle = dark ? { ...styles.body, ...styles.bodyDark } : styles.body;
|
|
19
21
|
return createPortal(
|
|
20
|
-
/* @__PURE__ */ jsx("div", { style: styles.overlay, role: "alertdialog", "aria-modal": "true", children: /* @__PURE__ */ jsxs("div", { style:
|
|
22
|
+
/* @__PURE__ */ jsx("div", { style: styles.overlay, role: "alertdialog", "aria-modal": "true", children: /* @__PURE__ */ jsxs("div", { style: modalStyle, children: [
|
|
21
23
|
/* @__PURE__ */ jsxs("h3", { style: styles.title, children: [
|
|
22
24
|
"\u6709\u65B0\u7248\u672C\u53EF\u7528",
|
|
23
25
|
version ? `\uFF1A${version}` : ""
|
|
24
26
|
] }),
|
|
25
|
-
changelogHtml ? /* @__PURE__ */ jsx("div", { style:
|
|
27
|
+
changelogHtml ? /* @__PURE__ */ jsx("div", { style: bodyStyle, dangerouslySetInnerHTML: { __html: changelogHtml } }) : /* @__PURE__ */ jsx("p", { style: { ...bodyStyle, color: dark ? "#9ca3af" : "#6b7280" }, children: "\u5237\u65B0\u9875\u9762\u5373\u53EF\u4F7F\u7528\u6700\u65B0\u7248\u672C\u3002" }),
|
|
26
28
|
/* @__PURE__ */ jsx("button", { type: "button", style: styles.primaryBtn, onClick: onRefresh, children: "\u7ACB\u5373\u66F4\u65B0" })
|
|
27
29
|
] }) }),
|
|
28
30
|
document.body
|
|
@@ -9,10 +9,19 @@ const props = withDefaults(defineProps<{
|
|
|
9
9
|
version?: string | null
|
|
10
10
|
/** Optional: e.g. `latestContent` from `virtual:refresh-guard-changelog`, rendered as-is via v-html — pre-sanitize if it isn't your own trusted file. */
|
|
11
11
|
changelogHtml?: string
|
|
12
|
+
/**
|
|
13
|
+
* Explicitly light/dark instead of following the OS `prefers-color-scheme`. Pass your app's
|
|
14
|
+
* own theme state here (e.g. `isDark.value`) so this modal matches your site's actual theme
|
|
15
|
+
* toggle instead of the visitor's OS setting — leaving this unset means a site in light mode
|
|
16
|
+
* can render a dark modal just because the OS is dark, which looks broken. Default: unset
|
|
17
|
+
* (falls back to `prefers-color-scheme`).
|
|
18
|
+
*/
|
|
19
|
+
dark?: boolean | null
|
|
12
20
|
}>(), {
|
|
13
21
|
mode: 'toast-auto',
|
|
14
22
|
version: null,
|
|
15
23
|
changelogHtml: '',
|
|
24
|
+
dark: null,
|
|
16
25
|
})
|
|
17
26
|
|
|
18
27
|
const emit = defineEmits<{ refresh: [] }>()
|
|
@@ -29,7 +38,7 @@ const shown = computed(() => props.visible && props.mode !== 'silent')
|
|
|
29
38
|
</div>
|
|
30
39
|
|
|
31
40
|
<div v-if="shown && mode === 'modal-blocking'" class="rg-overlay" role="alertdialog" aria-modal="true">
|
|
32
|
-
<div class="rg-modal">
|
|
41
|
+
<div class="rg-modal" :class="{ 'rg-dark': dark === true, 'rg-light': dark === false }">
|
|
33
42
|
<h3 class="rg-title">有新版本可用{{ version ? `:${version}` : '' }}</h3>
|
|
34
43
|
<div v-if="changelogHtml" class="rg-body" v-html="changelogHtml" />
|
|
35
44
|
<p v-else class="rg-body rg-body-empty">刷新页面即可使用最新版本。</p>
|
|
@@ -101,8 +110,10 @@ const shown = computed(() => props.visible && props.mode !== 'silent')
|
|
|
101
110
|
}
|
|
102
111
|
.rg-primary-btn:hover { background: #1d4ed8; }
|
|
103
112
|
|
|
113
|
+
.rg-modal.rg-dark { background: #1f2937; color: #f3f4f6; }
|
|
114
|
+
.rg-modal.rg-dark .rg-body { color: #d1d5db; }
|
|
104
115
|
@media (prefers-color-scheme: dark) {
|
|
105
|
-
.rg-modal { background: #1f2937; color: #f3f4f6; }
|
|
106
|
-
.rg-body { color: #d1d5db; }
|
|
116
|
+
.rg-modal:not(.rg-light) { background: #1f2937; color: #f3f4f6; }
|
|
117
|
+
.rg-modal:not(.rg-light) .rg-body { color: #d1d5db; }
|
|
107
118
|
}
|
|
108
119
|
</style>
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vite-plugin-refresh-guard",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "Configurable new-version detection + refresh for Vite apps
|
|
3
|
+
"version": "0.1.2",
|
|
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",
|
|
7
7
|
"repository": {
|