@leancodepl/force-update 8.5.0 → 8.5.1
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/README.md +109 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# @leancodepl/force-update
|
|
2
|
+
|
|
3
|
+
A library for implementing force update functionality in web applications.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @leancodepl/force-update
|
|
9
|
+
# or
|
|
10
|
+
yarn add @leancodepl/force-update
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
This package provides utilities to monitor application versions and prompt users to refresh when a new version is
|
|
16
|
+
available. It includes a Vite plugin for version endpoint creation and utilities for user notification on new version
|
|
17
|
+
available.
|
|
18
|
+
|
|
19
|
+
## API
|
|
20
|
+
|
|
21
|
+
### `listenOnForceUpdate(params)`
|
|
22
|
+
|
|
23
|
+
Sets up version monitoring with customizable callback and polling interval.
|
|
24
|
+
|
|
25
|
+
**Parameters:**
|
|
26
|
+
|
|
27
|
+
- `params: ForceUpdateParams` - Configuration object for force update listening
|
|
28
|
+
- `params.onNewVersionAvailable: () => void` - Callback function triggered when a new version is detected
|
|
29
|
+
- `params.versionCheckIntervalPeriod?: number` - Optional polling interval in milliseconds (default: 3 minutes)
|
|
30
|
+
|
|
31
|
+
**Returns:** Cleanup function to stop version monitoring
|
|
32
|
+
|
|
33
|
+
### `ForceUpdateNotification(props)`
|
|
34
|
+
|
|
35
|
+
React component that displays a browser prompt when a new version is available.
|
|
36
|
+
|
|
37
|
+
**Parameters:**
|
|
38
|
+
|
|
39
|
+
- `props.message?: string` - Optional custom message for notification prompt
|
|
40
|
+
|
|
41
|
+
**Returns:** React component that handles version checking and user notification
|
|
42
|
+
|
|
43
|
+
### `vitePluginForceUpdate(options)`
|
|
44
|
+
|
|
45
|
+
Vite plugin that creates a `/version` endpoint serving the current app version.
|
|
46
|
+
|
|
47
|
+
**Parameters:**
|
|
48
|
+
|
|
49
|
+
- `options: ForceUpdatePluginOptions` - Configuration options for the Vite plugin
|
|
50
|
+
- `options.envVariableName?: string` - Optional environment variable name (default: 'APP_VERSION')
|
|
51
|
+
|
|
52
|
+
**Returns:** Vite plugin instance
|
|
53
|
+
|
|
54
|
+
## Usage
|
|
55
|
+
|
|
56
|
+
### 1. Setup Version Monitoring
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
import { listenOnForceUpdate } from "@leancodepl/force-update"
|
|
60
|
+
|
|
61
|
+
useEffect(() => {
|
|
62
|
+
const cleanup = listenOnForceUpdate({
|
|
63
|
+
onNewVersionAvailable: () => {
|
|
64
|
+
// Show notification to user or force reload
|
|
65
|
+
if (window.confirm("A new version is available. Reload now?")) {
|
|
66
|
+
window.location.reload()
|
|
67
|
+
}
|
|
68
|
+
},
|
|
69
|
+
versionCheckIntervalPeriod: 5 * 60 * 1000, // Check every 5 minutes (optional)
|
|
70
|
+
})
|
|
71
|
+
|
|
72
|
+
return cleanup
|
|
73
|
+
}, [])
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
You can also use component with default behavior - displaying browser prompt with `window.confirm`.
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
import { ForceUpdateNotification } from "@leancodepl/force-update"
|
|
80
|
+
|
|
81
|
+
<ForceUpdateNotification
|
|
82
|
+
message="A new version of the app is available. Please reload the page to access latest features."
|
|
83
|
+
/>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### 2. Vite Plugin Setup
|
|
87
|
+
|
|
88
|
+
Add the plugin to your `vite.config.ts`:
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
import { defineConfig } from "vite"
|
|
92
|
+
import { vitePluginForceUpdate } from "@leancodepl/force-update"
|
|
93
|
+
|
|
94
|
+
export default defineConfig({
|
|
95
|
+
plugins: [vitePluginForceUpdate()],
|
|
96
|
+
})
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### 3. Set Environment Variable
|
|
100
|
+
|
|
101
|
+
Set the `APP_VERSION` environment variable during build.
|
|
102
|
+
|
|
103
|
+
## How It Works
|
|
104
|
+
|
|
105
|
+
1. The Vite plugin reads the `APP_VERSION` environment variable and creates a `/version` endpoint that serves the
|
|
106
|
+
current version. Environment variable name can be overridden.
|
|
107
|
+
2. The `listenOnForceUpdate` fetches initial version from the endpoint and then periodically polls it.
|
|
108
|
+
3. When a version mismatch is detected, it triggers the `onNewVersionAvailable` callback.
|
|
109
|
+
4. You can then prompt the user to reload or automatically refresh the page.
|