vite-plugin-refresh-guard 0.1.1 → 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 CHANGED
@@ -1,5 +1,16 @@
1
1
  # 更新日志
2
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
+
3
14
  ## v0.1.1 (2026-08-09)
4
15
 
5
16
  - README 改为中文正文 + 英文版(`README.en.md`),CHANGELOG/package.json 描述同步改中文为主
package/README.en.md CHANGED
@@ -52,6 +52,8 @@ This does two things at build time:
52
52
  <script setup lang="ts">
53
53
  import { useVersionCheck } from 'vite-plugin-refresh-guard/vue'
54
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
55
57
 
56
58
  const { hasUpdate, latestInfo, applyUpdate, mode } = useVersionCheck(__REFRESH_GUARD_VERSION__, {
57
59
  mode: 'toast-auto', // 'silent' | 'toast-auto' | 'modal-blocking'
@@ -59,21 +61,39 @@ const { hasUpdate, latestInfo, applyUpdate, mode } = useVersionCheck(__REFRESH_G
59
61
  </script>
60
62
 
61
63
  <template>
62
- <UpdatePrompt :visible="hasUpdate" :mode="mode" :version="latestInfo?.version" @refresh="applyUpdate" />
64
+ <UpdatePrompt
65
+ :visible="hasUpdate" :mode="mode" :version="latestInfo?.version"
66
+ :changelog-html="latestContent"
67
+ @refresh="applyUpdate"
68
+ />
63
69
  </template>
64
70
  ```
65
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
+
66
77
  **React**
67
78
 
68
79
  ```tsx
69
80
  import { useVersionCheck } from 'vite-plugin-refresh-guard/react'
70
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
71
83
 
72
84
  function App() {
73
85
  const { hasUpdate, latestInfo, applyUpdate, mode } = useVersionCheck(__REFRESH_GUARD_VERSION__, {
74
86
  mode: 'modal-blocking',
75
87
  })
76
- return <UpdatePrompt visible={hasUpdate} mode={mode} version={latestInfo?.version} onRefresh={applyUpdate} />
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
+ }
77
97
  }
78
98
  ```
79
99
 
package/README.md CHANGED
@@ -50,6 +50,8 @@ export default defineConfig({
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,21 +59,37 @@ const { hasUpdate, latestInfo, applyUpdate, mode } = useVersionCheck(__REFRESH_G
57
59
  </script>
58
60
 
59
61
  <template>
60
- <UpdatePrompt :visible="hasUpdate" :mode="mode" :version="latestInfo?.version" @refresh="applyUpdate" />
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 <UpdatePrompt visible={hasUpdate} mode={mode} version={latestInfo?.version} onRefresh={applyUpdate} />
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
 
@@ -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: styles.modal, children: [
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: styles.body, dangerouslySetInnerHTML: { __html: changelogHtml } }) : /* @__PURE__ */ jsx("p", { style: { ...styles.body, color: "#6b7280" }, children: "\u5237\u65B0\u9875\u9762\u5373\u53EF\u4F7F\u7528\u6700\u65B0\u7248\u672C\u3002" }),
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,6 +1,6 @@
1
1
  {
2
2
  "name": "vite-plugin-refresh-guard",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
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",