Registry / devops / react-cache-buster

react-cache-buster

library0.1.8jsnpmunverified

A lightweight React library for automatic cache busting in production builds. Version 0.1.8 provides a simple mechanism: during build, it generates a meta.json file containing the package version, and at runtime, a React component fetches that file, compares versions, and clears the cache/reloads the page if a new version is detected. It integrates with any React app (React >=17.0.2, Node >=10) and is TypeScript-friendly. Differentiators: zero-config setup via a single script and component, supports a custom loading component, and works with any hosting since meta.json can be served statically. Release cadence is irregular; last update was in 2021.

devops

npm install react-cache-buster

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-CACHE-BUSTER

react-cache-buster

devopsjavascriptv0.1.8

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CacheBuster

✓ import CacheBuster from 'react-cache-buster'

✗ const CacheBuster = require('react-cache-buster').default

Default export; named import like { CacheBuster } will fail. ESM-only in Node >=10, but CommonJS require works if you use .default.

generate-meta-tag script

✓ node ./node_modules/react-cache-buster/dist/generate-meta-tag.js

✗ npx react-cache-buster generate-meta-tag

This is a script, not an exported function. Run it as a Node command in package.json scripts.

version

✓ import { version } from '../package.json'

✗ import version from '../package.json'

Named import for the version field; default import may fail in certain bundler configurations.

Shows setup of the build script and wrapping the app with CacheBuster component.

// 1. Add script to package.json "scripts": { "build": "node ./node_modules/react-cache-buster/dist/generate-meta-tag.js && react-scripts build" } // 2. In App.jsx import React from 'react'; import CacheBuster from 'react-cache-buster'; import { version } from '../package.json'; import Loading from './Loading'; const App = () => { const isProduction = process.env.NODE_ENV === 'production'; return ( <CacheBuster currentVersion={version} isEnabled={isProduction} isVerboseMode={false} loadingComponent={<Loading />} metaFileDirectory={'.'} > <div>Your App</div> </CacheBuster> ); }; export default App;

Debug

Known issues

gotchaIf public assets are hosted in a subdirectory (e.g., /myapp/), the meta.json file must be served from that subdirectory. The metaFileDirectory prop should reflect the path relative to the public folder.

fix

Set metaFileDirectory to the subdirectory path (e.g., '/myapp/' or '.' if root).

affects: >=0.1.0

gotchaThe generate-meta-tag script overwrites public/meta.json on every build. If you have custom build steps that also modify meta.json, they may conflict.

fix

Ensure the script runs before other build steps that might write to public/meta.json.

affects: >=0.1.0

gotchaThe library only checks for version mismatch upon initial render. If the version changes while the app is open (e.g., after a hot reload in development), it will not trigger cache clearing.

fix

Use isEnabled to disable in development; the cache busting is intended for production only.

affects: >=0.1.0

gotchaThe meta.json file must be accessible via HTTP GET at the root of the hosted site (or the configured metaFileDirectory). If your server does not serve static files from that location, the fetch will fail silently.

fix

Verify that your server configuration serves the public folder as static content.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'react-cache-buster'

The package is not installed or is missing from node_modules.

fix

Run 'npm install react-cache-buster' or 'yarn add react-cache-buster'.

TypeError: cacheBusterRef.current is undefined

The CacheBuster component might be wrapped in a HOC or the ref is not forwarded correctly.

fix

Ensure you are not passing a ref to CacheBuster; it does not support ref forwarding.

Warning: Failed prop type: The prop `currentVersion` is marked as required in `CacheBuster`, but its value is `undefined`.

The currentVersion prop is not provided or is undefined.

fix

Pass a valid string version, e.g., currentVersion={version} from package.json.

Uncaught (in promise) TypeError: Failed to fetch

The meta.json file could not be fetched, likely due to network issues or wrong metaFileDirectory.

fix

Verify the meta.json exists in the public folder and the metaFileDirectory prop is correct. In production, the file must be served from the server.

Upgrade

Version history

0.1.8latest on npm

Audit

Dependencies

reactoptionalpeer dependency for the cache buster component

prop-typesoptionalpeer dependency for runtime type checking

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/CagriAldemir/react-cache-buster ↗

packagereact-cache-buster ↗

homepagehttps://github.com/CagriAldemir/react-cache-buster#readme ↗