Installation - @piplup/cache-buster
Install @piplup/cache-buster to detect that a new version of your React app is deployed and reload clients still running the old bundle.
@piplup/cache-buster is a lightweight React utility that ensures users always get the latest deployed version of your app.
npm install @piplup/cache-busterSetup build integration
Cache busting requires a release ID to be generated at build time.
Option 1: CLI
Update your package.json:
{
"scripts": {
"build": "piplup-cache-buster --publicDir=public && react-scripts build"
}
}This will:
- Generate a unique release ID
- Save it in your public/ directory
- Allow runtime comparison
Option 2: Vite plugin
If you're using Vite:
npm install @piplup/vite-plugin-cache-busterUpdate vite.config.(ts|mts|js|mjs):
import { vitePluginCacheBuster } from "@piplup/vite-plugin-cache-buster";
export default {
plugins: [vitePluginCacheBuster()],
};Why this step is required
The library works by comparing:
- Current release ID (from server)
- Stored release ID (in browser)
Without generating this file at build time, cache busting cannot work.
Next steps
- Wrap your app in
CacheBuster, or build your own prompt withuseReleaseStatus. - Reload users after a deploy covers the rest of the fix: cache
headers for
index.htmland recovering from lazy chunks a deploy removed.
Reload users after a deploy
Stop users running a stale React bundle after you deploy: cache index.html correctly, detect the new release, reload or prompt, and recover from failed chunk loads.
CacheBuster
Check for a new deployment when your app loads, and hold back rendering until the check is done, with the CacheBuster component.