dry crystal
When they click on links, the page doesn’t load and gets stuck
We don't want to refresh page
hollow roseBOT
Hi @dry crystal. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Based on the knowledge sources, I can see that your issue is related to version skew in Next.js, which occurs when users have an older version of your application open while a new deployment is released.
When Next.js detects a mismatch between the client's build ID and the server's build ID, it typically performs a hard navigation (full page reload) to retrieve new assets. According to the Next.js documentation on version skew:
Next.js will automatically mitigate most instances of version skew and automatically reload the application to retrieve new assets when detected. For example, if there is a mismatch in the
deploymentId, transitions between pages will perform a hard navigation versus using a prefetched value.
However, several GitHub issues indicate that this behavior can cause problems, particularly with:
clientSegmentCache FlagAccording to a comment in the Link prefetch issue, enabling the experimental clientSegmentCache flag may help:
{
experimental: {
clientSegmentCache: true,
}
}
Another comment in the same issue mentions that when PPR is enabled, the navigation issues are resolved.
If you're deploying on Vercel, they offer Skew Protection which routes client requests to their original deployment, preventing client-side state loss. This feature can be enabled in your project's Advanced settings on Vercel.
The knowledge sources indicate that completely avoiding page refreshes during version skew is challenging. The version skew documentation explicitly states:
When the application is reloaded, there may be a loss of application state if it's not designed to persist between page navigations.
dry crystal
@hollow rose How can I fix in self-deployed version
hollow roseBOT
Let me check the knowledge base for you again. Give me one moment! :books:
Based on the knowledge sources, here are the approaches you can take for a self-deployed Next.js application to handle version skew:
Configure a consistent build ID across your deployments using the generateBuildId option in next.config.js. According to the self-hosting documentation:
module.exports = {
generateBuildId: async () => {
// This could be anything, using the latest git hash
return process.env.GIT_HASH
},
}
This ensures that the same build uses the same ID across multiple containers or deployments.
A user shared a workaround in the Client cannot recover from version skew issue that uses middleware to detect version mismatches and handle them:
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import deploymentId from "./staticId";
export function middleware(request: NextRequest) {
if (request.nextUrl.pathname === "/refresh") {
return NextResponse.next();
}
const clientDeploymentId =
request.nextUrl.searchParams.get("dpl") ||
request.headers.get("x-deployment-id");
if (clientDeploymentId && clientDeploymentId !== deploymentId) {
const isAction =
request.method === "POST" && request.headers.has("Next-Action");
const refreshUrl = new URL("/refresh", request.url);
if (isAction) {
const response = NextResponse.next();
response.headers.set("x-action-redirect", refreshUrl.toString());
return response;
} else {
return NextResponse.redirect(refreshUrl);
}
}
}
Important caveat: The user notes that "You must set a deploymentId in every build, and to keep the deploymentId in sync from server to client, you should generate it in static in build time."
If you're using Server Actions, you can maintain consistent action IDs across deployments by setting the NEXT_SERVER_ACTIONS_ENCRYPTION_KEY environment variable. According to a comment in the version skew issue, this essentially opts out of the changing action IDs behavior when self-hosting.
useState.