Version skew happens when the browser expects one version of your application and the server sends another. Skew protection eliminates this by pinning each session to a specific Netlify deploy.
The version skew problem
When you build a web application that runs code on both the browser and the server, you’re creating an implicit contract between two fundamentally different environments. Breaking that contract is easier than you might think, and it can lead to a frustrating experience for your users.
Imagine an application that shows your music collection. When you click on an album, the application calls your API endpoint and does a client-side navigation to a page that shows the track list.
Your application will probably get updates and improvements over time. For example, you might decide to start showing more information about each album, like the release year.
Since you’re in control of both the client and the server, it should be easy to just update the shape of the data that is returned by your API endpoint. With Netlify, you can update your backend and your frontend in one single atomic operation, so when the next visitor comes in they’ll get the latest and greatest of what you built.
But what about existing clients? Imagine that someone opens your application, gets version 1 of your code running on their browser and starts interacting with the site.
In the meantime, you deploy your changes. The client is still clicking around, so the browser keeps calling the API. But now the server is running version 2 of the code, so it will start responding with a format that the client isn’t prepared to deal with.
This might cause the application to break entirely and it fixes itself only after a refresh pulls version 2.
Even if your application doesn’t explicitly call an API endpoint, this implicit contract is still there and can impact your users much more often than you’d expect.
Most modern web frameworks split the client-side code into smaller chunks that are requested on-demand by the browser as the user navigates around the application. These files are usually named with a fingerprint that associates them with a specific version of your application code (like chunk-a1b2c3.js).
When you re-deploy the application and get a completely different set of files, existing clients continue to request filenames that no longer exist and will get a 404.
How skew protection solves this
To talk about skew protection, it’s important to first understand how Netlify handles a new deploy under the hood.
When you update your application, we don’t exactly replace the old code with the new one — we keep both deploys available, but start pointing traffic to the new version. Think of it like changing your address to a brand new house rather than remodelling your existing place.
This versioned deploy system is the key to skew protection. When the client calls the server, it includes the version of the specific deploy it knows and expects.
When our CDN processes the request, it uses this version information to decide which deploy to point to. Even if we determine that your application is now on a newer version, we will respect the version that the client asked for and serve the request as if that version was still the one in use.
This information can be sent to the server in HTTP headers, query parameters or cookies. This ensures that we can cover every possible type of application and use case.
Framework support
Starting with version 5.15.0, Astro sites using the Netlify Adapter get skew protection enabled automatically. This means that features like actions, server islands, view transitions and prefetch requests are automatically protected from version skew.
If you use Next.js, you can opt in to this feature without making any changes to your application.
But more important than support for a set of frameworks on day one is our commitment to support any framework. We’ve only released skew protection once we were able to design it in a way that lets any framework benefit from it without any constraints.
With the Netlify Frameworks API, framework authors have full control over what paths are covered by skew protection and what signals are used to associate requests with a Netlify deploy.
We’re actively working with other frameworks to implement this feature and to incorporate their feedback into our design, so expect more announcements soon.
Pricing
Free. For everyone.
Getting started
Check out our skew protection docs to learn more about skew protection and to get information on how to get started with your framework of choice.
