Document version skew: `deploymentId` and `NEXT_DEPLOYMENT_ID` #88327

abdonrd · 2026-01-09T14:28:50Z

abdonrd
Jan 9, 2026

Goals

deploymentId is vaguely mentioned here:
https://nextjs.org/docs/app/guides/self-hosting#version-skew

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.

When the application is reloaded, there may be a loss of application state if it's not designed to persist between page navigations. For example, using URL state or local storage would persist state after a page refresh. However, component state like useState would be lost in such navigations.

And NEXT_DEPLOYMENT_ID is not even documented.

I think it would be useful to document what they consist of and how they should be configured.

Non-Goals

No response

Background

I haven't been able to find any clear documentation about it.

Some references:

Other external references:

https://opennext.js.org/cloudflare/howtos/skew#how-to-enable-the-skew-protection:~:text=You%20must%20set%20a%20different%20deploymentId

You must set a different deploymentId in your next config each time your app is deployed. You will get an error if the deployementId has already been used by a previous deployment.
https://vercel.com/docs/skew-protection#skew-protection-with-next.js

Proposal

Add it to Version Skew documentation:
https://nextjs.org/docs/app/guides/self-hosting#version-skew

Also add it to next.config.js documentation:
https://nextjs.org/docs/app/api-reference/config/next-config-js

Answered by icyJoseph

Mar 9, 2026

https://nextjs.org/docs/app/api-reference/config/next-config-js/deploymentId

This page documents both deploymentId and NEXT_DEPLOYMENT_ID

View full answer

icyJoseph · 2026-02-06T13:43:53Z

icyJoseph
Feb 6, 2026
Maintainer

Hi there, I've had this in on my queue of TODOs... just had to deal with other items, but I'll prioritize this once again.

2 replies

abdonrd Feb 6, 2026
Author

Thanks Joseph, I really appreciate it!

icyJoseph Feb 11, 2026
Maintainer

Since we are so far back on this... let's crowdsource a review:

https://github.com/vercel/next.js/pull/89795/changes

icyJoseph · 2026-03-09T11:09:39Z

icyJoseph
Mar 9, 2026
Maintainer

https://nextjs.org/docs/app/api-reference/config/next-config-js/deploymentId

This page documents both deploymentId and NEXT_DEPLOYMENT_ID

1 reply

abdonrd Mar 9, 2026
Author

Thanks Joseph!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document version skew: `deploymentId` and `NEXT_DEPLOYMENT_ID` #88327

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Version Skew

Replies: 2 comments 3 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Document version skew: deploymentId and NEXT_DEPLOYMENT_ID #88327

Uh oh!

Uh oh!

abdonrd Jan 9, 2026

Goals

Version Skew

Non-Goals

Background

Proposal

Replies: 2 comments · 3 replies

Uh oh!

icyJoseph Feb 6, 2026 Maintainer

Uh oh!

abdonrd Feb 6, 2026 Author

Uh oh!

icyJoseph Feb 11, 2026 Maintainer

Uh oh!

icyJoseph Mar 9, 2026 Maintainer

Uh oh!

abdonrd Mar 9, 2026 Author

Document version skew: `deploymentId` and `NEXT_DEPLOYMENT_ID` #88327

abdonrd
Jan 9, 2026

Replies: 2 comments 3 replies

icyJoseph
Feb 6, 2026
Maintainer

abdonrd Feb 6, 2026
Author

icyJoseph Feb 11, 2026
Maintainer

icyJoseph
Mar 9, 2026
Maintainer

abdonrd Mar 9, 2026
Author