Next.js Build Notifier
Relevant source files
The following files were used as context for generating this wiki page:
The Next.js Build Notifier is a headless system designed to detect when a newer deployment of a Next.js application is live and surface that state to the user interface. It provides a generic build detection mechanism with specialized support for Vercel's infrastructure, ensuring that clients can be notified of version skews without being forced into a specific UI implementation.
Sources: packages/next-build-notifier/README.md:1-5, packages/next-build-notifier/CHANGELOG.md:18-20
Architecture and Components
The system is composed of three primary layers: a build-time configuration wrapper, a server-side version endpoint, and a headless client-side API.
Build-Time Configuration
The withBuildNotifier function wraps the standard Next.js configuration. Its primary responsibility is to resolve a unique Build ID and inject it into the client bundle via the NEXT_PUBLIC_BUILD_ID environment variable. This ensures that every browser instance knows exactly which version of the application it is currently running.
Sources: packages/next-build-notifier/README.md:17-25, apps/storefront/next.config.js:154-154
Server-Side Detection
The server-side component utilizes a route handler factory, createVersionRoute, to expose an API endpoint (typically /api/version). This endpoint returns the Build ID of the currently live deployment. To ensure accuracy, the route is marked as force-dynamic and configured with Cache-Control: no-store to bypass framework-level and CDN caching.
Sources: packages/next-build-notifier/README.md:27-33, packages/next-build-notifier/CHANGELOG.md:6-12
Client-Side Logic
The client-side infrastructure consists of the BuildNotifierProvider, the useBuildNotification hook, and the <BuildNotifier> render-prop component. The provider monitors the version endpoint on specific triggers such as window focus, network reconnection, or a periodic interval.
Sources: packages/next-build-notifier/README.md:35-74
Data Flow
The following diagram illustrates the lifecycle of a Build ID from creation to detection.
The flow ensures that version detection is triggered by client activity or polling, comparing the "baked" ID against the "live" ID.
Sources: packages/next-build-notifier/README.md:77-85
Detection Logic and Version Skew
Detection relies on the comparison of two identifiers. The system resolves the Build ID using a specific precedence logic to ensure stability across different hosting environments.
Build ID Resolution Precedence
The resolveBuildId function determines the ID by checking the following variables in order:
NEXT_DEPLOYMENT_IDVERCEL_DEPLOYMENT_IDGIT_COMMIT_SHAVERCEL_GIT_COMMIT_SHANEXT_PUBLIC_BUILD_IDBUILD_ID- Fallback to the string literal
'development'
Sources: packages/next-build-notifier/README.md:79-81
Vercel Skew Protection
On Vercel, framework-level requests (like RSC payloads) are pinned to the deployment that served the initial page. However, a standard fetch call is not pinned and resolves against the deployment currently receiving traffic. This behavior is leveraged to detect when a new deployment has taken over the production traffic.
Sources: packages/next-build-notifier/README.md:87-92
Configuration Options
The BuildNotifierProvider accepts several properties to customize the behavior of the detection engine.
| Prop | Type | Default | Description |
|---|---|---|---|
currentBuildId | string | — | Required. The ID baked into the client via process.env.NEXT_PUBLIC_BUILD_ID. |
intervalMs | number | undefined | The polling interval in milliseconds. If falsy, periodic polling is disabled. |
endpoint | string | '/api/version' | The URL of the version route handler. |
fetcher | function | Built-in | Custom async function to handle the version request. |
Sources: packages/next-build-notifier/README.md:101-110
Implementation Example
The notifier is integrated into the workspace's storefront and other applications to handle live updates.
// Example Provider setup in app/providers.tsx
import { BuildNotifierProvider } from 'next-build-notifier';
export function Providers({ children }) {
return (
<BuildNotifierProvider
currentBuildId={process.env.NEXT_PUBLIC_BUILD_ID}
intervalMs={60000}
>
{children}
</BuildNotifierProvider>
);
}
Sources: packages/next-build-notifier/README.md:43-52, apps/storefront/next.config.js:154
The Next.js Build Notifier provides a critical bridge for multi-tenant or high-traffic applications where version skews can lead to failed client-side transitions or stale data. By abstracting the UI from the detection logic, it allows for seamless integration of update prompts or auto-reload behaviors across the commerce platform.
Sources: packages/next-build-notifier/README.md:5-10, packages/next-build-notifier/package.json:2-10