简体中文 | English
A tool for detecting new deployments in frontend applications. When a new deployment is detected in the production environment, it prompts users to refresh the page.
- 🔄 Automatic version detection
- 🔒 Version information encrypted with Base64
- ⚡️ Supports ESM and UMD formats
- 📦 TypeScript type definitions included
- 🛠 Built-in CLI tool
pnpm add fe-version-checker
During your project build process, use the built-in CLI tool to generate a version file:
npx generate-version -o ./public
# or after build
npx generate-version -o ./distThis will generate a version.json file in the specified directory containing the current version information.
// Option 1: Default import import VersionChecker from "fe-version-checker"; // Option 2: Named import (recommended) import { VersionChecker } from "fe-version-checker"; // If you need type definitions import type { VersionCheckerOptions, VersionInfo } from "fe-version-checker"; const checker = new VersionChecker({ // All options are optional interval: 30000, // Check interval, default 60000ms (1 minute) versionUrl: "/version.json", // Version file path, default '/version.json' message: "New version available. Refresh the page?", // Custom prompt message silent: false, // Whether to output logs to console, default false // Custom handler for new version detection // If not configured, will trigger `window.confirm` onNewVersion: () => { console.log("New version detected"); }, }); // Start checking checker.start(); // Stop checking // checker.stop();
Add build script to your package.json:
{
"scripts": {
"build": "generate-version -o ./public && your-build-command"
}
}import VersionChecker from "fe-version-checker"; import { useEffect } from "react"; import { message, Button } from "antd"; import { CloseOutlined } from "@ant-design/icons"; const App = () => { useEffect(() => { const showAntdMessage = () => { const key = "version-update"; message.info({ key, // Set key to avoid duplicate messages duration: 0, // Set to 0 to prevent auto-close content: ( <span> New version available. <a onClick={() => window.location.reload()}>Refresh</a> to get the latest updates <Button style={{ marginLeft: 10 }} size="small" type="text" icon={<CloseOutlined />} onClick={() => message.destroy(key)} /> </span> ), }); }; const checker = new VersionChecker({ interval: 30000, silent: true, onNewVersion: () => { // Use antd message component to show notification showAntdMessage(); }, }); // Start checking checker.start(); // Stop checking on component unmount return () => { checker.stop(); }; }, []); return ( <div> <h1>Your App Content</h1> </div> ); }; export default App;
Key configuration notes:
- Use unique
keyto prevent duplicate messages duration: 0keeps the message visible until manually closed- Use Button component as close button for better UX
| Parameter | Type | Default | Description |
|---|---|---|---|
| interval | number | 60000 | Check interval (milliseconds) |
| versionUrl | string | '/version.json' | Version file path |
| message | string | 'New version detected. Please refresh.' | Prompt message |
| onNewVersion | () => void | Default confirmation dialog | Callback for new version |
| silent | boolean | false | Disable console logs |
start(): Start version checkingstop(): Stop version checking
# Show help information generate-version -h # Generate version file in current directory generate-version # Generate version file in specified directory generate-version -o ./public generate-version --output ./dist # Specify filename generate-version -f custom.json # Generates custom.json generate-version -o ./public -f v1 # Generates v1.json in ./public
| Option | Short | Description | Default |
|---|---|---|---|
| --output | -o | Output directory | Current dir |
| --filename | -f | Output filename | version.json |
| --help | -h | Show help info | - |
- CLI tool generates a JSON file containing version information
- Version info includes version number and timestamp, encrypted with Base64
- Frontend periodically requests version file and compares with current version
- Triggers callback function when version mismatch is detected
- Generate version file during production build
- Host version file on CDN or static asset server
- Adjust check interval based on requirements
- Customize new version notification UI and interactions
- Enable silent mode in production
When using version checker in micro-frontend applications, absolute paths might cause resource request errors. Here's an example using micro-app:
const prefix = window.__MICRO_APP_ENVIRONMENT__ ? window.__MICRO_APP_PUBLIC_PATH__ : ""; const checker = new VersionChecker({ interval: 3000, silent: true, versionUrl: `${prefix}/version.json`, onNewVersion: () => { console.log("New version detected"); }, });
For
__MICRO_APP_PUBLIC_PATH__configuration, refer to micro-app documentation
// Triggered by new page, tab switch/close, browser minimize/close document.addEventListener("visibilitychange", () => { if (document.hidden) { checker.stop(); } else { checker.start(); } });
const router = createRouter({ ... }) router.beforeEach((to, from) => { checker.start() })
Implementation varies based on specific requirements.
MIT