Wrangler v4 migration guide

src/content/changelog/workers/2025-03-13-wrangler-v4.mdx

@@ -0,0 +1,21 @@
+---
+title: Use the latest JavaScript features with Wrangler CLI v4
+description: Wrangler v4 is available!
+products:
+  - workers
+date: 2025-02-28T22:30:00Z
+---
+
+import { PackageManagers } from "~/components";
+
+We've released the next major version of [Wrangler](/workers/wrangler/), the CLI for Cloudflare Workers — `[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:
+
+<PackageManagers pkg="wrangler@latest" />
+
+Unlike previous major versions of Wrangler, which were [foundational rewrites](https://blog.cloudflare.com/wrangler-v2-beta/) and [rearchitectures](https://blog.cloudflare.com/wrangler3/) — 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](/workers/wrangler/migration/update-v3-to-v4) 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](https://github.com/cloudflare/workers-sdk/issues/new?template=bug-template.yaml).
+
+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.

src/content/docs/pages/framework-guides/deploy-a-hono-site.mdx

@@ -70,7 +70,7 @@ Open your `package.json` file and update the `scripts` section:
         "dev:wrangler": "wrangler pages dev dist --live-reload",
         "dev:esbuild": "esbuild --bundle src/server.js --format=esm --watch --outfile=dist/_worker.js",
         "build": "esbuild --bundle src/server.js --format=esm --outfile=dist/_worker.js",
-        "deploy": "wrangler pages publish dist"
+        "deploy": "wrangler pages deploy dist"
     },
 ```
 
@@ -82,7 +82,7 @@ Open your `package.json` file and update the `scripts` section:
         "dev:wrangler": "wrangler pages dev dist --live-reload",
         "dev:esbuild": "esbuild --bundle src/server.ts --format=esm --watch --outfile=dist/_worker.js",
         "build": "esbuild --bundle src/server.ts --format=esm --outfile=dist/_worker.js",
-        "deploy": "wrangler pages publish dist"
+        "deploy": "wrangler pages deploy dist"
     },
 ```
 

src/content/docs/pages/functions/typescript.mdx

@@ -5,27 +5,33 @@ sidebar:
   order: 8
 ---
 
+import { PackageManagers, Render } from "~/components";
+
 Pages Functions supports TypeScript. Author any files in your `/functions` directory with a `.ts` extension instead of a `.js` extension to start using TypeScript.
 
-To add the runtime types to your project, run:
+You can add runtime types and Env types by running:
 
-```sh
-npm install --save-dev typescript @cloudflare/workers-types
-```
+<PackageManagers
+	type="exec"
+	pkg="wrangler"
+	args={"types --path='./functions/types.d.ts'"}
+/>
 
-Then configure the runtime types by creating a `functions/tsconfig.json` file:
+Then configure the types by creating a `functions/tsconfig.json` file:
 
 ```json
 {
 	"compilerOptions": {
 		"target": "esnext",
 		"module": "esnext",
 		"lib": ["esnext"],
-		"types": ["@cloudflare/workers-types"]
+		"types": ["./types.d.ts"]
 	}
 }
 ```
 
+See [the `wrangler types` command docs](/workers/wrangler/commands/#types) for more details.
+
 If you already have a `tsconfig.json` at the root of your project, you may wish to explicitly exclude the `/functions` directory to avoid conflicts. To exclude the `/functions` directory:
 
 ```json
@@ -36,7 +42,9 @@ If you already have a `tsconfig.json` at the root of your project, you may wish
 }
 ```
 
-Pages Functions can be typed using the `PagesFunction` type. This type accepts an `Env` parameter. To use the `env` parameter:
+Pages Functions can be typed using the `PagesFunction` type. This type accepts an `Env` parameter. The `Env` type should have been generated by `wrangler types` and can be found at the top of `types.d.ts`.
+
+Alternatively, you can define the `Env` type manually. For example:
 
 ```ts
 interface Env {
@@ -48,3 +56,22 @@ export const onRequest: PagesFunction<Env> = async (context) => {
 	return new Response(value);
 };
 ```
+
+If you are using `nodejs_compat`, make sure you have installed `@types/node` and updated your `tsconfig.json`.
+
+```json
+{
+	"compilerOptions": {
+		"target": "esnext",
+		"module": "esnext",
+		"lib": ["esnext"],
+		"types": ["./types.d.ts", "node"]
+	}
+}
+```
+
+:::note
+
+If you were previously using `@cloudflare/workers-types` instead of the runtime types generated by `wrangler types`, you can refer to this [migration guide](/workers/languages/typescript/#migrating).
+
+:::

src/content/docs/workers/configuration/multipart-upload-metadata.mdx

@@ -68,11 +68,6 @@ At a minimum, the `main_module` key is required to upload a Worker.
 
   * [Compatibility Flags](/workers/configuration/compatibility-flags/#setting-compatibility-flags) that enable or disable certain features in the Workers runtime. Used to enable upcoming features or opt in or out of specific changes not included in a `compatibility_date`.
 
-* `usage_model` <Type text="string" /> <MetaInfo text="optional" />
-
-  * Usage model to apply to invocations, only allowed value is `standard`.
-
-
 
 ## Additional attributes: [Workers Script Upload API](/api/resources/workers/subresources/scripts/methods/update/)
 

src/content/docs/workers/languages/javascript/index.mdx

@@ -6,7 +6,6 @@ sidebar:
 
 ---
 
-## JavaScript
 
 The Workers platform is designed to be [JavaScript standards compliant](https://ecma-international.org/publications-and-standards/standards/ecma-262/) and web-interoperable, and supports JavaScript standards, as defined by [TC39](https://tc39.es/) (ECMAScript). Wherever possible, it uses web platform APIs, so that code can be reused across client and server, as well as across [WinterCG](https://wintercg.org/) JavaScript runtimes.
 

src/content/docs/workers/languages/typescript/index.mdx

@@ -8,107 +8,128 @@ head:
     content: Write Cloudflare Workers in TypeScript
 ---
 
-import { TabItem, Tabs } from "~/components";
+import { TabItem, Tabs, PackageManagers, Render } from "~/components";
 
-## TypeScript
+TypeScript is a first-class language on Cloudflare Workers. All APIs provided in Workers are fully typed, and type definitions are generated directly from [workerd](https://github.com/cloudflare/workerd), the open-source Workers runtime.
 
-TypeScript is a first-class language on Cloudflare Workers. Cloudflare publishes type definitions to [GitHub](https://github.com/cloudflare/workers-types) and [npm](https://www.npmjs.com/package/@cloudflare/workers-types) (`npm install -D @cloudflare/workers-types`). All APIs provided in Workers are fully typed, and type definitions are generated directly from [workerd](https://github.com/cloudflare/workerd), the open-source Workers runtime.
+We recommend you generate types for your Worker by running [`wrangler types`](/workers/wrangler/commands/#types). Cloudflare also publishes type definitions to [GitHub](https://github.com/cloudflare/workers-types) and [npm](https://www.npmjs.com/package/@cloudflare/workers-types) (`npm install -D @cloudflare/workers-types`).
 
-### Generate types that match your Worker's configuration (experimental)
+<h3 id="generate-types">
+	Generate types that match your Worker's configuration
+</h3>
 
 Cloudflare continuously improves [workerd](https://github.com/cloudflare/workerd), the open-source Workers runtime.
-Changes in workerd can introduce JavaScript API changes, thus changing the respective TypeScript types. For example, the [`urlsearchparams_delete_has_value_arg`](/workers/configuration/compatibility-flags/#urlsearchparams-delete-and-has-value-argument) compatibility flag adds optional arguments to some methods, in order to support new additions to the WHATWG URL standard API.
+Changes in workerd can introduce JavaScript API changes, thus changing the respective TypeScript types.
 
-This means the correct TypeScript types for your Worker depend on:
+This means the correct types for your Worker depend on:
 
-1. Your Worker's [Compatibility Date](/workers/configuration/compatibility-dates/).
-2. Your Worker's [Compatibility Flags](/workers/configuration/compatibility-flags/).
+1. Your Worker's [compatibility date](/workers/configuration/compatibility-dates/).
+2. Your Worker's [compatibility flags](/workers/configuration/compatibility-flags/).
+3. Your Worker's bindings, which are defined in your [Wrangler configuration file](/workers/wrangler/configuration).
+4. Any [module rules](/workers/wrangler/configuration/#bundling) you have specified in your Wrangler configuration file under `rules`.
 
-For example, if you have `compatibility_flags = ["nodejs_als"]` in your [Wrangler configuration file](/workers/wrangler/configuration/), then the runtime will allow you to use the [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) class in your worker code, but you will not see this reflected in the type definitions in `@cloudflare/workers-types`.
+For example, the runtime will only allow you to use the [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) class if you have `compatibility_flags = ["nodejs_als"]` in your [Wrangler configuration file](/workers/wrangler/configuration/). This should be reflected in the type definitions.
 
-In order to solve this issue, and to ensure that your type definitions are always up-to-date with your compatibility settings, you can dynamically generate the runtime types (as of `wrangler 3.66.0`):
+To ensure that your type definitions always match your Worker's configuration, you can dynamically generate types by running:
 
-```bash
-npx wrangler types --experimental-include-runtime
-```
+<PackageManagers type="exec" pkg="wrangler" args={"types"} />
 
-This will generate a `d.ts` file and (by default) save it to `.wrangler/types/runtime.d.ts`. You will be prompted in the command's output to add that file to your `tsconfig.json`'s `compilerOptions.types` array.
+See [the `wrangler types` command docs](/workers/wrangler/commands/#types) for more details.
 
-If you would like to commit the file to git, you can provide a custom path. Here, for instance, the `runtime.d.ts` file will be saved to the root of your project:
+:::note
 
-```bash
-npx wrangler types --experimental-include-runtime="./runtime.d.ts"
-```
+<Render file="wrangler-commands/runtime-types" product="workers" />
 
-**Note: To ensure that your types are always up-to-date, make sure to run `wrangler types --experimental-include-runtime` after any changes to your config file.**
+:::
 
-See [the full list of available flags](/workers/wrangler/commands/#types) for more details.
+This will generate a `d.ts` file and (by default) save it to `worker-configuration.d.ts`. This will include `Env` types based on your Worker bindings _and_ runtime types based on your Worker's compatibility date and flags.
 
-#### Migrating from `@cloudflare/workers-types` to `wrangler types --experimental-include-runtime`
+You should then add that file to your `tsconfig.json`'s `compilerOptions.types` array. If you have the `nodejs_compat` compatibility flag, you should also install `@types/node`.
 
-The `@cloudflare/workers-types` package provides runtime types for each distinct [compatibility date](https://github.com/cloudflare/workerd/tree/main/npm/workers-types#compatibility-dates), which is specified by the user in their `tsconfig.json`. But this package is superseded by the `wrangler types --experimental-include-runtime` command.
+You can commit your types file to git if you wish.
 
-Here are the steps to switch from `@cloudflare/workers-types` to using `wrangler types` with the experimental runtime inclusion:
+:::note
 
-##### Uninstall `@cloudflare/workers-types`
+To ensure that your types are always up-to-date, make sure to run `wrangler types` after any changes to your config file.
 
-<Tabs> <TabItem label="npm">
+:::
 
-```sh
-npm uninstall @cloudflare/workers-types
-```
+<h3 id="migrating">
+	Migrating from `@cloudflare/workers-types` to `wrangler types`
+</h3>
 
-</TabItem> <TabItem label="yarn">
+We recommend you use `wrangler types` to generate runtime types, rather than using the `@cloudflare/workers-types` package, as it generates types based on your Worker's [compatibility date](https://github.com/cloudflare/workerd/tree/main/npm/workers-types#compatibility-dates) and `compatibility flags`, ensuring that types match the exact runtime APIs made available to your Worker. 
 
-```sh
-yarn remove @cloudflare/workers-types
-```
+:::note
 
-</TabItem> <TabItem label="pnpm">
+There are no plans to stop publishing the `@cloudflare/workers-types` package, which will still be the recommended way to type libraries and shared packages in the workers environment.
 
-```sh
-pnpm uninstall @cloudflare/workers-types
-```
+:::
 
-</TabItem> </Tabs>
+#### 1. Uninstall `@cloudflare/workers-types`
 
-##### Generate runtime types using wrangler
+<PackageManagers type="remove" pkg="@cloudflare/workers-types" />
 
-```bash
-npx wrangler types --experimental-include-runtime
-```
+#### 2. Generate runtime types using Wrangler
 
-This will generate a `.d.ts` file, saved to `.wrangler/types/runtime.d.ts` by default.
+<PackageManagers type="exec" pkg="wrangler" args={"types"} />
 
-##### Update your `tsconfig.json` to include the generated types
+This will generate a `.d.ts` file, saved to `worker-configuration.d.ts` by default. This will also generate `Env` types. If for some reason you do not want to include those, you can set `--include-env=false`.
+
+You can now remove any imports from `@cloudflare/workers-types` in your Worker code.
+
+:::note
+
+<Render file="wrangler-commands/runtime-types" product="workers" />
+
+:::
+
+#### 3. Make sure your `tsconfig.json` includes the generated types
 
 ```json
 {
 	"compilerOptions": {
-		"types": ["./.wrangler/types/runtime"]
+		"types": ["worker-configuration.d.ts"]
 	}
 }
 ```
 
 Note that if you have specified a custom path for the runtime types file, you should use that in your `compilerOptions.types` array instead of the default path.
 
-##### Update your scripts and CI pipelines
+#### 4. Add @types/node if you are using [`nodejs_compat`](/workers/runtime-apis/nodejs/) (Optional)
+
+If you are using the `nodejs_compat` compatibility flag, you should also install `@types/node`.
+
+<PackageManagers type="add" pkg="@types/node" />
+
+Then add this to your `tsconfig.json`.
+
+```json
+{
+	"compilerOptions": {
+		"types": ["worker-configuration.d.ts", "node"]
+	}
+}
+```
+
+#### 5. Update your scripts and CI pipelines
 
-When switching to `wrangler types --experimental-include-runtime`, you'll want to ensure that your development process always uses the most up-to-date types. The main thing to remember here is that - regardless of your specific framework or build tools - you should run the `wrangler types --experimental-include-runtime` command before any development tasks that rely on TypeScript. This ensures your editor and build tools always have access to the latest types.
+Regardless of your specific framework or build tools, you should run the `wrangler types` command before any tasks that rely on TypeScript.
 
-Most projects will have existing build and development scripts, as well as some type-checking. In the example below, we're adding the `wrangler types --experimental-include-runtime` before the type-checking script in the project:
+Most projects will have existing build and development scripts, as well as some type-checking. In the example below, we're adding the `wrangler types` before the type-checking script in the project:
 
 ```json
 {
 	"scripts": {
 		"dev": "existing-dev-command",
-		"build": "-existing-build-command",
-		"type-check": "wrangler types --experimental-include-runtime && tsc"
+		"build": "existing-build-command",
+		"generate-types": "wrangler types",
+		"type-check": "generate-types && tsc"
 	}
 }
 ```
 
-In CI, you may have separate build and test commands. It is best practice to run `wrangler types --experimental-include-runtime` before other CI commands. For example:
+We recommend you commit your generated types file for use in CI. Alternatively, you can run `wrangler types` before other CI commands, as it should not take more than a few seconds. For example:
 
 <Tabs> <TabItem label="npm">
 
@@ -136,26 +157,6 @@ In CI, you may have separate build and test commands. It is best practice to run
 
 </TabItem> </Tabs>
 
-By integrating the `wrangler types --experimental-include-runtime` command into your workflow this way, you ensure that your development environment, builds, and CI processes always use the most accurate and up-to-date types for your Cloudflare Worker, regardless of your specific framework or tooling choices.
-
-### Known issues
-
-#### Transitive loading of `@types/node` overrides `@cloudflare/workers-types`
-
-Your project's dependencies may load the `@types/node` package on their own. As of `@types/[email protected]` that package now overrides `Request`, `Response` and `fetch` types (possibly others) specified by `@cloudflare/workers-types` causing type errors.
-
-The way to get around this issue currently is to pin the version of `@types/node` to `20.8.3` in your `package.json` like this:
-
-```json
-{
-	"overrides": {
-		"@types/node": "20.8.3"
-	}
-}
-```
-
-For more information, refer to [this GitHub issue](https://github.com/cloudflare/workerd/issues/1298).
-
 ### Resources
 
 - [TypeScript template](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare/templates/hello-world/ts)

src/content/docs/workers/observability/logs/logpush.mdx

@@ -24,7 +24,7 @@ Workers Trace Events Logpush is not available for zones on the [Cloudflare China
 ## Verify your Logpush access
 
 :::note[Wrangler version]
-Minimum required Wrangler version: 2.2.0. Check your version by running `wrangler version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).
+Minimum required Wrangler version: 2.2.0. Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).
 :::
 
 To configure a Logpush job, verify that your Cloudflare account role can use Logpush. To check your role:

src/content/docs/workers/observability/logs/workers-logs.mdx

@@ -24,7 +24,7 @@ To send logs to a third party, use [Workers Logpush](/workers/observability/logs
 ## Enable Workers Logs
 
 :::note[Wrangler version]
-Minimum required Wrangler version: 3.78.6. Check your version by running `wrangler version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).
+Minimum required Wrangler version: 3.78.6. Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).
 :::
 
 You must add the observability setting for your Worker to write logs to Workers Logs. Add the following setting to your Worker's Wrangler file and redeploy your Worker.

src/content/docs/workers/tutorials/github-sms-notifications-using-twilio/index.mdx

@@ -237,7 +237,7 @@ async fetch(request, env, ctx) {
 };
 ```
 
-Run the `npx wrangler publish` command to redeploy your Worker project:
+Run the `npx wrangler deploy` command to redeploy your Worker project:
 
 ```sh
 npx wrangler deploy