Compatibility dates
Cloudflare regularly updates the Workers runtime. These updates apply to all Workers globally and should never cause a Worker that is already deployed to stop functioning. Sometimes, though, some changes may be backwards-incompatible. In particular, there might be bugs in the runtime API that existing Workers may inadvertently depend upon. Cloudflare implements bug fixes that new Workers can opt into while existing Workers will continue to see the buggy behavior to prevent breaking deployed Workers.
The compatibility date and flags are how you, as a developer, opt into these runtime changes. Compatibility flags will often have a date in which they are enabled by default, and so, by specifying a compatibility_date for your Worker, you can quickly enable all of these various compatibility flags up to, and including, that date.
When you start your project, you should always set compatibility_date to the current date. You should occasionally update the compatibility_date field. When updating, you should refer to the compatibility flags page to find out what has changed, and you should be careful to test your Worker to see if the changes affect you, updating your code as necessary. The new compatibility date takes effect when you next run the npx wrangler deploy command.
There is no need to update your compatibility_date if you do not want to. The Workers runtime will support old compatibility dates forever. If, for some reason, Cloudflare finds it is necessary to make a change that will break live Workers, Cloudflare will actively contact affected developers. That said, Cloudflare aims to avoid this if at all possible.
However, even though you do not need to update the compatibility_date field, it is a good practice to do so for two reasons:
- Sometimes, new features can only be made available to Workers that have a current
compatibility_date. To access the latest features, you need to stay up-to-date. - Generally, other than the compatibility flags page, the Workers documentation may only describe the current
compatibility_date, omitting information about historical behavior. If your Worker uses an oldcompatibility_date, you will need to continuously refer to the compatibility flags page in order to check if any of the APIs you are using have changed.
The compatibility date can be set in a Worker's wrangler.toml file.
# Opt into backwards-incompatible changes through April 5, 2022.compatibility_date = "2022-04-05"When a Worker is created through the Cloudflare Dashboard, the compatibility date is automatically set to the current date.
The compatibility date can be updated in the Workers settings on the Cloudflare dashboard ↗.
The compatibility date can be set when uploading a Worker using the Workers Script API or Workers Versions API in the request body's metadata field.
If a compatibility date is not specified on upload via the API, it defaults to the oldest compatibility date, before any flags took effect (2021-11-02). When creating new Workers, it is highly recommended to set the compatibility date to the current date when uploading via the API.