[email protected]

We've released the next major version of Wrangler — [email protected]. Wrangler v4 is a major release focused on updates to underlying systems and dependencies, along with improvements to keep Wrangler commands consistent and clear.

You can run the following command to install it in your projects:

Unlike previous major versions of Wrangler, which were foundational rewrites and rearchitectures — Version 4 of Wrangler includes a much smaller set of changes. If you use Wrangler today, your workflow is very unlikely to change.

A detailed migration guide is available and if you find a bug or hit a roadblock when upgrading to Wrangler v4, open an issue on the cloudflare/workers-sdk repository on GitHub.

Going forward, we'll continue supporting Wrangler v3 with bug fixes and security updates until Q1 2026, and with critical security updates until Q1 2027, at which point it will be out of support.

The full changelog is available at https://github.com/cloudflare/workers-sdk/blob/main/packages/wrangler/CHANGELOG.md#400

[email protected]

Patch Changes

• #8393 c4653081c Thanks @penalosa! - Deprecate Wrangler v2. Since the release of Wrangler v3 in 2023, we’ve seen great adoption, and today over 95% of active Wrangler usage is with v3.

  As such, Wrangler v2 is now deprecated, and no new features or bug fixes are being published for v2. We strongly recommend you upgrade to the latest version of Wrangler to receive continued support. We have a migration guide to make this process easy! If you encounter any difficulties, please let us know by filing an issue.

[email protected]

Major Changes

• #7334 869ec7b Thanks @penalosa! - The --node-compat flag and node_compat config properties are no longer supported as of Wrangler v4. Instead, use the nodejs_compat compatibility flag. This includes the functionality from legacy node_compat polyfills and natively implemented Node.js APIs. See https://developers.cloudflare.com/workers/runtime-apis/nodejs for more information.

  If you need to replicate the behaviour of the legacy node_compat feature, refer to https://developers.cloudflare.com/workers/wrangler/migration/update-v3-to-v4/ for a detailed guide.

• #7334 869ec7b Thanks @penalosa! - Packages in Workers SDK now support the versions of Node that Node itself supports (Current, Active, Maintenance). Currently, that includes Node v18, v20, and v22.

@cloudflare/[email protected]

Minor Changes

• #7334 869ec7b Thanks @penalosa! - Packages in Workers SDK now support the versions of Node that Node itself supports (Current, Active, Maintenance). Currently, that includes Node v18, v20, and v22.

@cloudflare/[email protected]

Minor Changes

• #7334 869ec7b Thanks @penalosa! - Packages in Workers SDK now support the versions of Node that Node itself supports (Current, Active, Maintenance). Currently, that includes Node v18, v20, and v22.

@cloudflare/[email protected]

Minor Changes

• #7334 869ec7b Thanks @threepointone! - chore: update esbuild

  This patch updates esbuild from 0.17.19 to 0.24.2. That's a big bump! Lots has gone into esbuild since May '23. All the details are available at https://github.com/evanw/esbuild/blob/main/CHANGELOG.md / https://github.com/evanw/esbuild/blob/main/CHANGELOG-2023.md.

  • We now support all modern JavasScript/TypeScript features suported by esbuild (as of December 2024). New additions include standard decorators, auto-accessors, and the using syntax.

  • 0.18 introduced wider support for configuration specified via tsconfig.json evanw/esbuild#3019. After observing the (lack of) any actual broken code over the last year for this release, we feel comfortable releasing this without considering it a breaking change.

  • 0.19.3 introduced support for import attributes

    import stuff from './stuff.json' with { type: 'json' }

    While we don't currently expose the esbuild configuration for developers to add their own plugins to customise how modules with import attributes are bundled, we may introduce new "types" ourselves in the future.

  • 0.19.0 introduced support for wildcard imports. Specifics here (https://github.com/evanw/esbuild/blob/main/CHANGELOG-2023.md#0190). tl;dr -

    • These 2 patterns will bundle all files that match the glob pattern into a single file.

      const json1 = await import("./data/" + kind + ".json");

      const json2 = await import(`./data/${kind}.json`);

    • This pattern will NOT bundle any matching patterns:

      const path = "./data/" + kind + ".js";
      const json2 = await import(path);

      You can use find_additional_modules to bundle any additional modules that are not referenced in the code but are required by the project.

    Now, this MAY be a breaking change for some. Specifically, if you were previously using the pattern (that will now include all files matching the glob pattern in the bundle), BUT find_additional_modules was NOT configured to include some files, those files would now be included in the bundle. For example, consider this code:

    // src/index.js
    export default {
    	async fetch() {
    		const url = new URL(request.url);
    		const name = url.pathname;
    		const value = (await import("." + name)).default;
    		return new Response(value);
    	},
    };

    Imagine if in that folder, you had these 3 files:

    // src/one.js
    export default "one";

    // src/two.js
    export default "two";

    // src/hidden/secret.js
    export default "do not share this secret";

    And your wrangler.toml was:

    name = "my-worker"
    main = "src/index.js

    Before this update:

    1. A request to anything but http://localhost:8787/ would error. For example, a request to http://localhost:8787/one.js would error with No such module "one.js".
    2. Let's configure wrangler.toml to include all .js files in the src folder:

    name = "my-worker"
    main = "src/index.js
    
    find_additional_modules = true
    rules = [
      { type = "ESModule", globs = ["*.js"]}
    ]

    Now, a request to http://localhost:8787/one.js would return the contents of src/one.js, but a request to http://localhost:8787/hidden/secret.js would error with No such module "hidden/secret.js". To include this file, you could expand the rules array to be:

    rules = [
      { type = "ESModule", globs = ["**/*.js"]}
    ]

    Then, a request to http://localhost:8787/hidden/secret.js will return the contents of src/hidden/secret.js.

    After this update:

    • Let's put the wrangler.toml back to its original configuration:

    name = "my-worker"
    main = "src/index.js

    • Now, a request to http://localhost:8787/one.js will return the contents of src/one.js, but a request to http://localhost:8787/hidden/secret.js will ALSO return the contents of src/hidden/secret.js. THIS MAY NOT BE WHAT YOU WANT. You can "fix" this in 2 ways:

      1. Remove the inline wildcard import:

      // src/index.js
      export default {
      	async fetch() {
      		const name = new URL(request.url).pathname;
      		const moduleName = "./" + name;
      		const value = (await import(moduleName)).default;
      		return new Response(value);
      	},
      };

      Now, no extra modules are included in the bundle, and a request to http://localhost:8787/hidden/secret.js will throw an error. You can use the find_additional_modules feature to include it again.

      2. Don't use the wildcard import pattern:

      // src/index.js
      import one from "./one.js";
      import two from "./two.js";
      
      export default {
      	async fetch() {
      		const name = new URL(request.url).pathname;
      		switch (name) {
      			case "/one.js":
      				return new Response(one);
      			case "/two.js":
      				return new Response(two);
      			default:
      				return new Response("Not found", { status: 404 });
      		}
      	},
      };

      Further, there may be some files that aren't modules (js/ts/wasm/text/binary/etc) that are in the folder being included (For example, a photo.jpg file). This pattern will now attempt to include them in the bundle, and throw an error. It will look like this:

      [ERROR] No loader is configured for ".png" files: src/photo.jpg

      To fix this, simply move the offending file to a different folder.

      In general, we DO NOT recommend using the wildcard import pattern. If done wrong, it can leak files into your bundle that you don't want, or make your worker slightly slower to start. If you must use it (either with a wildcard import pattern or with find_additional_modules) you must be diligent to check that your worker is working as expected and that you are not leaking files into your bundle that you don't want. You can configure eslint to disallow dynamic imports like this:

      // eslint.config.js
      export default [
      	{
      		rules: {
      			"no-restricted-syntax": [
      				"error",
      				{
      					selector: "ImportExpression[argument.type!='Literal']",
      					message:
      						"Dynamic imports with non-literal arguments are not allowed.",
      				},
      			],
      		},
      	},
      ];

Patch Changes

• Updated dependencies [869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b]:
  • [email protected]
  • [email protected]

@cloudflare/[email protected]

Patch Changes

• Updated dependencies [869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b, 869ec7b]:
  • [email protected]
  • [email protected]
  • @cloudflare/[email protected]

@cloudflare/[email protected]

Patch Changes

• Updated dependencies [869ec7b, 869ec7b]:
  • [email protected]
  • @cloudflare/[email protected]

@cloudflare/[email protected]

Minor Changes

• #7334 869ec7b Thanks @penalosa! - Packages in Workers SDK now support the versions of Node that Node itself supports (Current, Active, Maintenance). Currently, that includes Node v18, v20, and v22.

[email protected]

Patch Changes

• #8383 8d6d722 Thanks @matthewdavidrodgers! - Make kv bulk put --local respect base64:true

  The bulk put api has an optional "base64" boolean property for each key.
  Before storing the key, the value should be decoded from base64.

  For real (remote) kv, this is handled by the rest api. For local kv, it
  seems the base64 field was ignored, meaning encoded base64 content was
  stored locally rather than the raw values.

  To fix, we need to decode each value before putting to the local
  miniflare namespace when base64 is true.

• #8273 e3efd68 Thanks @penalosa! - Support AI, Vectorize, and Images bindings when using @cloudflare/vite-plugin

• #8427 a352798 Thanks @vicb! - update unenv-preset dependency to fix bug with Performance global

  Fixes #8407
  Fixes #8409
  Fixes #8411

• #8390 53e6323 Thanks @GregBrimble! - Parse and apply metafiles (_headers and _redirects) in wrangler dev for Workers Assets

• #8392 4d9d9e6 Thanks @jahands! - fix: retry zone and route lookup API calls

  In rare cases, looking up Zone or Route API calls may fail due to transient errors. This change improves the reliability of wrangler deploy when these errors occur.

  Also fixes a rare issue where concurrent API requests may fail without correctly throwing an error which may cause a deployment to incorrectly appear successful.

• Updated dependencies [8242e07, 53e6323]:

  • [email protected]