deploymentId
Source URL: https://nextjs.org/docs/app/api-reference/config/next-config-js/deploymentId
deploymentId
Section titled “deploymentId”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.
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 buildGood to know: If both are set, the
deploymentIdvalue innext.config.jstakes precedence over theNEXT_DEPLOYMENT_IDenvironment variable.
How it works
Section titled “How it works”When a deploymentId is configured, Next.js:
- Appends
?dpl=<deploymentId>to static asset URLs (JavaScript, CSS, images) - Adds an
x-deployment-idheader to client-side navigation requests - Adds an
x-nextjs-deployment-idheader to navigation responses - Injects a
data-dpl-idattribute on the<html>element
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 and Server Functions 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
Section titled “Use cases”Rolling deployments
Section titled “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
- Server Functions work correctly across deployment boundaries
Multi-server environments
Section titled “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.
module.exports = { deploymentId: process.env.DEPLOYMENT_VERSION || process.env.GIT_SHA,}Version History
Section titled “Version History”| Version | Changes |
|---|---|
v14.1.4 | deploymentId stabilized as top-level config option. |
v13.4.10 | experimental.deploymentId introduced. |