This page is also available as Markdown: request this page's URL with an Accept: text/markdown header. For an index of Next.js Pages Router documentation, see /docs/pages/llms.txt.

You are currently viewing the documentation for Pages Router.

deploymentId

Last updated February 12, 2026

The deploymentId option allows you to set an identifier for your deployment. This identifier is used for version skew protection and cache busting during rolling deployments.

next.config.js

module.exports = {
  deploymentId: 'my-deployment-id',
}

You can also set the deployment ID using the NEXT_DEPLOYMENT_ID environment variable:

NEXT_DEPLOYMENT_ID=my-deployment-id next build

Good to know: If both are set, the deploymentId value in next.config.js takes precedence over the NEXT_DEPLOYMENT_ID environment variable.

How it works

When a deploymentId is configured, Next.js:

Appends ?dpl=<deploymentId> to static asset URLs (JavaScript, CSS, images)
Adds an x-deployment-id header to client-side navigation requests
Adds an x-nextjs-deployment-id header to navigation responses
Injects a data-dpl-id attribute on the <html> element
Includes the deploymentId in the 'use cache' cache key, invalidating cache entries when the deployment ID changes

When the client detects a mismatch between its deployment ID and the server's (via the response header), it triggers a hard navigation (full page reload) instead of a client-side navigation. This ensures users always receive assets from a consistent deployment version.

Good to know: Next.js does not read the ?dpl= query parameter on incoming requests. The query parameter is for cache busting (ensuring browsers and CDNs fetch fresh assets), not for routing. If you need version-aware routing, consult your hosting provider or CDN's documentation for implementing deployment-based routing.

Use cases

Rolling deployments

During a rolling deployment, some server instances may be running the new version while others are still running the old version. Without a deployment ID, users might receive a mix of old and new assets, causing errors.

Setting a consistent deploymentId per deployment ensures:

Clients always request assets from a matching deployment version
Mismatches trigger a full reload to fetch the correct assets

Multi-server environments

When running multiple instances of your Next.js application behind a load balancer, all instances for the same deployment should use the same deploymentId.