Cloudflare Workers · Wrangler · all subjects

compatibility-dates

26 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Compatibility date definition and purpose

The compatibility date is a setting that allows developers to opt into specific versions of the Workers runtime. Cloudflare regularly updates the Workers runtime globally, and some changes may be backwards-incompatible. Compatibility dates enable developers to opt into bug fixes and new behavior while ensuring existing Workers continue to function with their expected behavior.

Set compatibility_date to current date when starting a project

When you start your project, you should always set the compatibility_date to the current date. This ensures you have access to the latest features and runtime behavior.

Updating compatibility_date takes effect on next deploy

The new compatibility date takes effect when you next run the npx wrangler deploy command.

Workers runtime supports old compatibility dates forever

There is no requirement to update the compatibility_date if you do not want to. The Workers runtime will support old compatibility dates indefinitely. Cloudflare will actively contact affected developers if a change would break live Workers.

Reasons to update compatibility_date regularly

Two reasons support keeping your compatibility_date current: (1) new features can only be made available to Workers that have a current compatibility_date, and (2) the Workers documentation generally only describes the current compatibility_date, omitting information about historical behavior. Using an old compatibility_date requires continuously referring to the compatibility flags page.

Compatibility date set automatically in Cloudflare Dashboard

When a Worker is created through the Cloudflare Dashboard, the compatibility date is automatically set to the current date. It can be updated later in the Workers settings on the Cloudflare dashboard.

Set compatibility_date via Workers Script API and Workers Versions API

The compatibility date can be set when uploading a Worker using the Workers Script API or Workers Versions API by including it in the request body's metadata field.

Default compatibility_date when not specified in API uploads

If a compatibility date is not specified when uploading a Worker via the API, it defaults to 2021-11-02, which is the oldest compatibility date before any flags took effect. When creating new Workers via API, it is highly recommended to set the compatibility date to the current date.

What are compatibility flags

Compatibility flags enable specific features in the Workers runtime. They can be useful to help test upcoming changes not yet enabled by default, or to hold back a change that code depends on while applying other compatibility changes.

Compatibility flags and compatibility_date relationship

Compatibility flags will often have a date in which they are enabled by default. By specifying a compatibility_date for a Worker, all compatibility flags up to and including that date are automatically enabled.

Setting compatibility flags via Cloudflare Dashboard

Compatibility flags can be updated in the Workers settings on the Cloudflare dashboard at https://dash.cloudflare.com/.

Setting compatibility flags via Cloudflare API

Compatibility flags can be set when uploading a Worker using the Workers Script API or Workers Versions API in the request body's metadata field.

nodejs_compat flag behavior with compatibility date 2024-09-23 or later

The nodejs_compat flag automatically enables nodejs_compat_v2 when the compatibility date is 2024-09-23 or later. The v2 flag improves runtime Node.js compatibility by bundling additional polyfills and globals into the Worker, but increases bundle size.

nodejs_compat and nodejs_compat_v2 with compatibility date 2024-09-22 or before

If compatibility date is 2024-09-22 or before and nodejs_compat_v2 is desired, add nodejs_compat_v2 to the compatibility_flags in addition to the nodejs_compat flag.

Disabling nodejs_compat_v2 with compatibility date after 2024-09-23

If compatibility date is after 2024-09-23 but nodejs_compat_v2 should be disabled to avoid increasing bundle size, add the no_nodejs_compat_v2 flag to compatibility_flags in addition to the nodejs_compat flag.

nodejs_compat flag enables Node.js APIs

The nodejs_compat compatibility flag enables a growing subset of Node.js APIs available directly as Runtime APIs in Workers, with no need to add polyfills to code. It is added to the compatibility_flags array in the Wrangler configuration file.

nodejs_compat flag will not become default by default

Unlike most other compatibility flags, nodejs_compat is not expected to become active by default at a future date as additional Node.js APIs are added.

nodejs_als compatibility flag for AsyncLocalStorage

The nodejs_als compatibility flag enables only the Node.js AsyncLocalStorage API in Workers. It is useful as a standalone alternative to enabling the full nodejs_compat flag.

Experimental compatibility flags

Some compatibility flags are experimental and can be enabled via compatibility_flags, but are not yet scheduled to become default on any particular date.

Metadata compatibility_date attribute

The compatibility_date string attribute (optional) indicates targeted support in the Workers runtime. Backwards incompatible fixes to the runtime following this date will not affect this Worker. It is highly recommended to set a compatibility_date; otherwise if uploading via the API, it defaults to 2021-11-02 (the oldest compatibility date before any flags took effect).

Metadata compatibility_flags attribute

The compatibility_flags array of strings (optional) enables or disables certain features in the Workers runtime. It is used to enable upcoming features or opt in or out of specific changes not included in a compatibility_date.

process.env with nodejs_compat and nodejs_compat_populate_process_env

When nodejs_compat is enabled and the nodejs_compat_populate_process_env compatibility flag is enabled (enabled by default for compatibility dates on or after 2025-04-01), environment variables are available via the global process.env. Text variable values are exposed directly. JSON variable values that evaluate to string values are exposed as the parsed value. JSON variable values that do not evaluate to string values are exposed as the raw JSON string.

process.env is populated lazily

The process.env will be populated lazily the first time that process is accessed in the worker when nodejs_compat and nodejs_compat_populate_process_env are enabled.

Example: process.env with nodejs_compat

Example showing how environment variables are exposed via process.env with nodejs_compat enabled: [vars] FOO = "abc" BAR = "abc" BAZ = { "a": 123 } The values of process.env.FOO and process.env.BAR will each be the JavaScript string "abc". The value of process.env.BAZ will be the JSON-encoded string "{ \"a\": 123 }".

compatibility_date property for latest features

Update the compatibility_date property in wrangler.jsonc to today's date to get access to the most recent Workers features. The format is yyyy-mm-dd.

Compatibility date in documentation

In documentation examples, the compatibility_date field should use the $today placeholder for auto-replacement rather than a hardcoded date to avoid staleness.

Give your agent this brain