React Zero Downtime Build

> Eliminate chunk load errors and 404s during deployments with automatic version detection and user prompts.


The Problem

When you deploy a new version of your React app:
- Users on old versions get chunk load errors (ChunkLoadError)
- Static assets return 404 errors because old chunks are deleted
- Users have to manually refresh, leading to poor UX

The Solution

react-zero-downtime-build automatically:
1. Checks for new versions every minute (configurable)
2. Detects when a new build is deployed
3. Shows a user-friendly prompt with two options:
- Refresh: Standard page reload
- Hard Refresh: Clears cache and reloads

Features

- ✅ Adapter-based architecture - Works with react-scripts, Vite, and Webpack
- ✅ Zero configuration - Works out of the box with sensible defaults
- ✅ Git Integration - Automatically captures commit author, message, and hash
- ✅ Premium UI - Styled with modern glassmorphism and clear visual hierarchy
- ✅ No-Dismiss Enforcement - Ensures users always stay on the latest version
- ✅ TypeScript support - Full type safety
- ✅ Customizable UI - Use built-in components or build your own

Installation

One-command setup (recommended):

``bash
npx @thisisayande/rzd init
`

This will automatically:
- Install @thisisayande/rzd package
- Create rzd.config.js in your project root
- Update your package.json build script to use rzd build
- Backup your original build script as build:original

Or install manually:

`bash
npm install @thisisayande/rzd
npx rzd init
`

Quick Start

$3

`bash
npx @thisisayande/rzd init
`

This will:
- Install the package (if not already installed)
- Create rzd.config.js in your project root
- Update your package.json build script to use rzd build
- Backup your original build script as build:original

$3

`tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { VersionProvider } from '@thisisayande/rzd';
// Import the auto-generated version info
import {
CURRENT_VERSION,
CURRENT_BUILD_ID,
CURRENT_BUILD_TIME
} from './version';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root')!);

root.render(

intervalMs={10000} // Check every 10 seconds
currentVersion={CURRENT_VERSION}
currentBuildId={CURRENT_BUILD_ID}
currentBuildTime={CURRENT_BUILD_TIME}
>



);
`

$3

To ensure git metadata (author, message) is captured:

1. Commit your changes:
`bash
git add .
git commit -m "feat: your amazing feature"
`

2. Run the build:
`bash
npm run build
`

The build process will automatically fetch the latest git info and embed it into your build!

The build process will automatically:
1. Generate a version file (app-version.json)
2. Build your application
3. Place the version file in your build output

Configuration

Edit rzd.config.js in your project root:

`javascript
module.exports = {
// Build adapter: 'react-scripts', 'vite', or 'webpack'
adapter: 'react-scripts',

// Output directory
outputDir: 'build',

// Check for updates every 60 seconds
checkInterval: 60000,

// Version endpoint
versionEndpoint: '/app-version.json',

// Enable debug logging
debug: false,

// Environment variables for build
env: {
REACT_APP_API_URL: 'https://api.example.com',
},
};
`

API Reference

$3

Provides version checking context to your app.

`tsx

{/ Your app /}

`

Props:
- intervalMs (optional): Check interval in milliseconds (default: 60000)
- currentVersion (optional): The initial version string
- currentBuildId (optional): The initial build ID (git hash)
- currentAuthor (optional): The initial git author
- currentCommitMessage (optional): The initial git commit message
- currentBuildTime (optional): The initial build timestamp
- autoPrompt (optional): Automatically show the update prompt (default: true)
- children: React nodes

$3

Access version information and control functions.

`tsx
const {
current, // Current version info
latest, // Latest version from server
updateAvailable, // Boolean indicating if update is available
checkNow, // Manually trigger version check
reload, // Standard page refresh
hardReload, // Clear cache and refresh
} = useVersion();
`

$3

Banner-style notification at top or bottom of screen.

`tsx
show={updateAvailable}
onRefresh={reload}
onHardRefresh={hardReload}
position="top"
message="A customized message"
commitAuthor="John Doe"
buildId="a1b2c3d"
commitMessage="feat: added something awesome"
/>
`

$3

Modal-style dialog in center of screen.

`tsx
show={showPrompt}
onRefresh={reload}
onHardRefresh={hardReload}
message="A customized message"
commitAuthor="John Doe"
buildId="a1b2c3d"
commitMessage="feat: added something awesome"
/>
`

Advanced Usage

$3

Build your own update notification:

`tsx
import { useVersion } from '@thisisayande/rzd';

function CustomUpdateNotification() {
const { updateAvailable, current, latest, reload, hardReload } = useVersion();

if (!updateAvailable) return null;

return (



);
}
`

$3

`tsx
const { checkNow } = useVersion();

// Trigger check on user action

Check for Updates

`

How It Works

1. Build Time: During build, a app-version.json file is generated with version info, buildId, and timestamp
2. Runtime: The app periodically fetches this file to check for updates
3. Detection: If the buildId differs, updateAvailable becomes true`
4. User Action: User clicks "Refresh" or "Hard Refresh" to update

Supported Build Tools

- ✅ Create React App (react-scripts)
- ✅ Vite
- ✅ Webpack

Browser Support

Works in all modern browsers that support:
- Fetch API
- LocalStorage
- ES6+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC

Author

vksco

Support

- GitHub Issues
- Documentation