Ever deployed a new version of your app and wished your users got notified instantly while they’re still using the old one? In this post, I'll show you how I built a live build checker in my Next.js app that detects when a new deployment is live and gently nudges users to refresh using a toast notification.
Use case: Helpful for apps deployed on Vercel where static pages and edge functions make it easy to serve outdated content across sessions.
The Stack
Next.js 15
React 19
React-Bootstrap
React-Toastify
Vercel Edge Functions
Supabase Auth (optional)
The Concept
When a new build is deployed, a unique timestamp (NEXT_PUBLIC_BUILD_TIMESTAMP) is injected into the environment. On the client, we poll an API endpoint every few minutes to check if the server's build timestamp has changed. If it has, we notify the user.
Step-by-Step Implementation
1. Add a build timestamp during build time
In next.config.ts:
const now = new Date().toISOString();
const nextConfig = {
env: {
NEXT_PUBLIC_BUILD_TIMESTAMP: now,
},
};
export default nextConfig;
This ensures every build has a unique timestamp baked in at compile time.
2. Create a /api/build route
This edge function returns the current server build timestamp:
import { NextRequest } from "next/server";
export const runtime = "edge";
export async function GET(request: NextRequest) {
return new Response(
JSON.stringify({ build: process.env.NEXT_PUBLIC_BUILD_TIMESTAMP }),
{
headers: { "Content-Type": "application/json" },
}
);
}
You can also add authentication here if needed, e.g., for private dashboards.
3. Build a custom hook: useLiveBuildChecker
This hook polls the /api/build endpoint periodically and triggers a toast if it detects a new version:
import { useEffect, useRef } from "react";
import { toast } from "react-toastify";
import axios from "axios";
export function useLiveBuildChecker(intervalMin = 5) {
const currentBuild = useRef(
process.env.NEXT_PUBLIC_BUILD_TIMESTAMP
);
useEffect(() => {
const checkForUpdate = async () => {
try {
const res = await axios.get("/api/build");
const { build } = res.data;
if (build && build !== currentBuild.current) {
toast.info("A new version of this page is available. Refresh to see the latest changes.", {
autoClose: false,
position: "bottom-right",
});
clearInterval(interval);
}
} catch (e) {
console.error("Update check failed:", e);
}
};
const interval = setInterval(
checkForUpdate,
process.env.NODE_ENV === "development" ? 5 * 1000 : intervalMin * 60 * 1000
);
return () => clearInterval(interval);
}, [intervalMin]);
}
4. Add Toast UI + Hook in Layout
Update your app layout to include the ToastContainer and run the hook:
"use client";
import { ReactNode } from "react";
import { ToastContainer } from "react-toastify";
import { useLiveBuildChecker } from "@/hooks/useLiveBuildChecker";
import "react-toastify/dist/ReactToastify.css";
interface Props {
children: ReactNode;
}
export default function AppLayout({ children }: Props) {
useLiveBuildChecker(); // default 5-min interval
return (
<>
{children}
<ToastContainer />
</>
);
}
Result
Whenever a new version of your app is deployed, users still active in the browser will get this neat toast:
"A new version of this page is available. Refresh to see the latest changes."
Why This Works
This approach is fully edge-friendly, stateless, and easy to scale. And unlike service worker-based update detection, it works great for SSR/ISR setups and custom dashboards.
Bonus Ideas
Final Thoughts
Keeping users on the latest version of your app improves stability, security, and experience. With just a few lines of code, you can achieve this kind of real-time deploy awareness in any Next.js app.
If you're building a dashboard, personal tool, or even a SaaS product, this is one of those delightfully simple yet powerful improvements.
