A simple modern utility to clear cache and reload the application.
npm install react-cache-refreshA modern, lightweight React utility that automatically detects new app versions and clears browser caches to ensure users always get the latest version of your application.
- Automatic Version Detection: Compares current app version with latest deployed version
- Smart Cache Clearing: Clears all browser caches (Service Worker caches, HTTP caches)
- React 19 Compatible: Built with modern React patterns and hooks
- TypeScript Support: Full TypeScript support with type definitions
- Reload Protection: Prevents infinite reload loops with built-in cooldown mechanism
- Error Resilient: Gracefully handles missing meta.json or network errors
- Configurable Logging: Hide console logs in production with hideConsoleLogs option
- Custom Loading States: Show custom loading components during version checks
- Zero Dependencies: Only requires React as a peer dependency
``bash`
npm install react-cache-refreshor
yarn add react-cache-refreshor
pnpm add react-cache-refresh
First, create a meta.json file in your public directory with your app version:
`json`
{
"version": "1.0.0"
}
`tsx
import React from "react";
import { CacheBuster } from "react-cache-refresh";
import App from "./App";
const VERSION = "1.0.0"; // This should match your package.json version
function Root() {
return (
loadingComponent={
export default Root;
`
Make sure to update the meta.json file with the new version number whenever you deploy:
`json`
{
"version": "1.0.1"
}
The main component that wraps your application and handles version checking.
#### Props
| Prop | Type | Required | Default | Description |
| ------------------- | ----------- | -------- | ------- | ----------------------------------------------------- |
| children | ReactNode | ✅ | - | Your app components |currentAppVersion
| | string | ✅ | - | Current version of your app |loadingComponent
| | ReactNode | ❌ | null | Custom loading component (shown during version check) |hideConsoleLogs
| | boolean | ❌ | false | Hide console logs for version checking process |
#### Example with Custom Loading and Options
`tsx
import React from "react";
import { CacheBuster } from "react-cache-refresh";
import App from "./App";
import LoadingSpinner from "./components/LoadingSpinner";
const VERSION = "1.0.0";
function Root() {
return (
loadingComponent={
hideConsoleLogs={process.env.NODE_ENV === "production"}
>
);
}
`
#### clearAllCaches()
Manually clear all browser caches.
`tsx
import { clearAllCaches } from "react-cache-refresh/utils";
const handleClearCache = async () => {
try {
await clearAllCaches();
console.log("All caches cleared successfully");
} catch (error) {
console.error("Error clearing caches:", error);
}
};
`
For production environments, you might want to hide the version checking console logs:
`tsx
import React from "react";
import { CacheBuster } from "react-cache-refresh";
import App from "./App";
const VERSION = "1.0.0";
function Root() {
return (
hideConsoleLogs={process.env.NODE_ENV === "production"}
>
);
}
`
`tsx
import React from "react";
import { CacheBuster } from "react-cache-refresh";
import App from "./App";
// Get version from environment variable or package.json
const VERSION = process.env.REACT_APP_VERSION || "1.0.0";
function Root() {
return (
hideConsoleLogs={process.env.NODE_ENV === "production"}
>
);
}
`
`tsx
import React from "react";
import { CacheBuster } from "react-cache-refresh";
import App from "./App";
const LoadingComponent = () => (
function Root() {
return (
loadingComponent={
>
);
}
`
By default, react-cache-refresh provides helpful console logs during the version checking process:
- Version Check: Shows current and latest versions
- Success: Confirms when versions match
- Updates: Logs when version mismatch is detected
- Errors: Reports any issues with version checking
Example console output:
`console`
Current app version: 1.0.0
Latest app version: 1.0.1
Version mismatch detected - clearing caches and reloading
You can disable these logs in production using the hideConsoleLogs prop:
`tsx`
hideConsoleLogs={process.env.NODE_ENV === "production"}
>
#### Basic Example (Package.json Versioning)
`yaml`GitHub Actions
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- run: echo '{"version":"'$(node -p "require('./package.json').version")'"}' > public/meta.json
- run: npm ci && npm run build
#### Dynamic Versioning (Recommended)
Generate unique versions using Git SHA + Pipeline ID:
`yaml`GitHub Actions
name: Deploy with Dynamic Versioning
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Generate version
run: |
VERSION="${GITHUB_REF#refs/heads/}.$(date -u +%Y%m%d%H%M%S).$(git rev-parse --short HEAD).${{ github.run_id }}"
echo '{"version":"'$VERSION'"}' > public/meta.json
echo "REACT_APP_VERSION=$VERSION" > .env.production
- run: npm ci && npm run build
`tsx
// In your React app
const VERSION = process.env.REACT_APP_VERSION || "dev-local";
`
More CI/CD Examples (GitLab, Azure, etc.)
#### GitLab CI
`yaml`.gitlab-ci.yml
build:
script:
- VERSION="${CI_COMMIT_REF_NAME}.$(date -u +%Y%m%d%H%M%S).${CI_COMMIT_SHORT_SHA}.${CI_PIPELINE_ID}"
- echo "{\"version\": \"${VERSION}\"}" > public/meta.json
- echo "REACT_APP_VERSION=${VERSION}" > .env.production
- npm ci && npm run build
#### Azure DevOps
`yaml`azure-pipelines.yml
variables:
version: $(Build.SourceBranchName).$(Build.BuildId)
steps:
- script: |
echo "{\"version\": \"$(version)\"}" > public/meta.json
echo "REACT_APP_VERSION=$(version)" > .env.production
npm ci && npm run build
#### Version Formats
`bash`Examples of generated versions:
"main.20241001143022.a1b2c3d.12345" # branch.date.sha.buildid
"20241001143022.a1b2c3d.12345" # date.sha.buildid (shorter)
"a1b2c3d.12345" # sha.buildid (minimal)
#### Using with Webpack
`javascript
// webpack.config.js
const fs = require("fs");
const packageJson = require("./package.json");
// Update meta.json during build
fs.writeFileSync(
"public/meta.json",
JSON.stringify({
version: packageJson.version,
})
);
`
Ensure meta.json is never cached by adding these headers:
Nginx:
`nginx`
location /meta.json {
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
Apache:
`apache`
Header set Cache-Control "no-cache, no-store, must-revalidate"
1. Version Check → Fetches /meta.json on app load
2. Comparison → Compares with current app version
3. Cache Clear → Clears all browser caches if versions differ
4. Reload → Hard reload to get latest version
5. Cooldown → 5-second safety to prevent reload loops
| Issue | Solution |
| ----------------------- | ------------------------------------------------------------------ |
| Infinite reloads | Ensure meta.json and app versions match during deployment |meta.json
| Version check fails | Check exists and isn't cached by your server |/public` |
| 404 for meta.json | Component handles this gracefully - just add the file to
Debug: Check browser console for version logs and error details.
Found a bug or have a feature request? Please open an issue on GitHub.
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the ISC License.
- GitHub Repository
- NPM Package
- Report Issues
---
Made with ❤️ for the React community