Compatibility flags

import { WranglerConfig, Render } from "/components"; import CompatibilityFlags from "/components/cf/CompatibilityFlags.astro";

Compatibility flags enable specific features. They can be useful if you want to help the Workers team test upcoming changes that are not yet enabled by default, or if you need to hold back a change that your code depends on but still want to apply other compatibility 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.

Setting compatibility flags

You may provide a list of compatibility_flags, which enable or disable specific changes.

Via Wrangler

Compatibility flags can be set in a Worker's Wrangler configuration file.

This example enables the specific flag formdata_parser_supports_files, which is described below. As of the specified date, 2021-09-14, this particular flag was not yet enabled by default, but, by specifying it in compatibility_flags, we can enable it anyway. compatibility_flags can also be used to disable changes that became the default in the past.

{
	// Opt into backwards-incompatible changes through September 14, 2021.
	"compatibility_date": "2021-09-14",
	// Also opt into an upcoming fix to the FormData API.
	"compatibility_flags": [
		"formdata_parser_supports_files"
	]
}

Via the Cloudflare Dashboard

Compatibility flags can be updated in the Workers settings on the Cloudflare dashboard.

Via the 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.

Node.js compatibility flag

:::note The nodejs_compat flag also enables nodejs_compat_v2 for compatibility dates from 2024-09-23 through 2026-08-03. The v2 flag improves Node.js compatibility by bundling additional polyfills and globals into your Worker. However, this improvement increases bundle size.

For compatibility dates through 2024-09-22, add nodejs_compat_v2 alongside nodejs_compat to turn on v2. For compatibility dates from 2024-09-23 through 2026-08-03, add no_nodejs_compat_v2 alongside nodejs_compat to use v1 only. :::

A growing subset of Node.js APIs are available directly as Runtime APIs, with no need to add polyfills to your own code.

For compatibility dates of 2026-08-04 or later, Workers enables both nodejs_compat and nodejs_compat_v2 by default. These flags are not used for these compatibility dates because the compatibility date enables the same behavior. Wrangler, Miniflare, the Cloudflare Vite plugin, and the Workers Vitest plugin ignore these redundant flags when starting the runtime. Existing projects do not need to remove them when updating their compatibility date. Omit them from new configurations.

To turn off Node.js compatibility completely for a compatibility date of 2026-08-04 or later, remove nodejs_compat and nodejs_compat_v2 if present. Then add both of the following flags:

{
	"compatibility_flags": [
		"no_nodejs_compat",
		"no_nodejs_compat_v2"
	]
}

The Node.js AsyncLocalStorage API is a particularly useful feature for Workers. To enable only the AsyncLocalStorage API, use the nodejs_als compatibility flag.

{
	"compatibility_flags": [
		"nodejs_als"
	]
}

Flags history

Newest flags are listed first.

Experimental flags

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