You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Use the latest JavaScript features with Wrangler CLI v4
3
+
description: Wrangler v4 is available!
4
+
products:
5
+
- workers
6
+
date: 2025-03-13T09:00:00Z
7
+
---
8
+
9
+
import { PackageManagers } from"~/components";
10
+
11
+
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.
12
+
13
+
You can run the following command to install it in your projects:
14
+
15
+
<PackageManagerspkg="wrangler@latest" />
16
+
17
+
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.
18
+
19
+
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).
20
+
21
+
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.
Pages Functions supports TypeScript. Author any files in your `/functions` directory with a `.ts` extension instead of a `.js` extension to start using TypeScript.
9
11
10
-
To add the runtime types to your project, run:
12
+
You can add runtime types and Env types by running:
Then configure the runtime types by creating a `functions/tsconfig.json` file:
20
+
Then configure the types by creating a `functions/tsconfig.json` file:
17
21
18
22
```json
19
23
{
20
24
"compilerOptions": {
21
25
"target": "esnext",
22
26
"module": "esnext",
23
27
"lib": ["esnext"],
24
-
"types": ["@cloudflare/workers-types"]
28
+
"types": ["./types.d.ts"]
25
29
}
26
30
}
27
31
```
28
32
33
+
See [the `wrangler types` command docs](/workers/wrangler/commands/#types) for more details.
34
+
29
35
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:
30
36
31
37
```json
@@ -36,7 +42,9 @@ If you already have a `tsconfig.json` at the root of your project, you may wish
36
42
}
37
43
```
38
44
39
-
Pages Functions can be typed using the `PagesFunction` type. This type accepts an `Env` parameter. To use the `env` parameter:
45
+
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`.
46
+
47
+
Alternatively, you can define the `Env` type manually. For example:
If you are using `nodejs_compat`, make sure you have installed `@types/node` and updated your `tsconfig.json`.
61
+
62
+
```json
63
+
{
64
+
"compilerOptions": {
65
+
"target": "esnext",
66
+
"module": "esnext",
67
+
"lib": ["esnext"],
68
+
"types": ["./types.d.ts", "node"]
69
+
}
70
+
}
71
+
```
72
+
73
+
:::note
74
+
75
+
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).
Copy file name to clipboardExpand all lines: src/content/docs/workers/configuration/multipart-upload-metadata.mdx
-5Lines changed: 0 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -68,11 +68,6 @@ At a minimum, the `main_module` key is required to upload a Worker.
68
68
69
69
*[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`.
Copy file name to clipboardExpand all lines: src/content/docs/workers/languages/javascript/index.mdx
-1Lines changed: 0 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,6 @@ sidebar:
6
6
7
7
---
8
8
9
-
## JavaScript
10
9
11
10
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.
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.
14
14
15
-
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.
15
+
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`).
16
16
17
-
### Generate types that match your Worker's configuration (experimental)
17
+
<h3id="generate-types">
18
+
Generate types that match your Worker's configuration
19
+
</h3>
18
20
19
21
Cloudflare continuously improves [workerd](https://github.com/cloudflare/workerd), the open-source Workers runtime.
20
-
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.
22
+
Changes in workerd can introduce JavaScript API changes, thus changing the respective TypeScript types.
21
23
22
-
This means the correct TypeScript types for your Worker depend on:
24
+
This means the correct types for your Worker depend on:
23
25
24
-
1. Your Worker's [Compatibility Date](/workers/configuration/compatibility-dates/).
25
-
2. Your Worker's [Compatibility Flags](/workers/configuration/compatibility-flags/).
26
+
1. Your Worker's [compatibility date](/workers/configuration/compatibility-dates/).
27
+
2. Your Worker's [compatibility flags](/workers/configuration/compatibility-flags/).
28
+
3. Your Worker's bindings, which are defined in your [Wrangler configuration file](/workers/wrangler/configuration).
29
+
4. Any [module rules](/workers/wrangler/configuration/#bundling) you have specified in your Wrangler configuration file under `rules`.
26
30
27
-
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`.
31
+
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.
28
32
29
-
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`):
33
+
To ensure that your type definitions always match your Worker's configuration, you can dynamically generate types by running:
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.
37
+
See [the `wrangler types` command docs](/workers/wrangler/commands/#types) for more details.
36
38
37
-
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: 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.**
43
+
:::
44
44
45
-
See [the full list of available flags](/workers/wrangler/commands/#types) for more details.
45
+
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.
46
46
47
-
#### Migrating from `@cloudflare/workers-types`to `wrangler types --experimental-include-runtime`
47
+
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`.
48
48
49
-
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.
49
+
You can commit your types file to git if you wish.
50
50
51
-
Here are the steps to switch from `@cloudflare/workers-types` to using `wrangler types` with the experimental runtime inclusion:
51
+
:::note
52
52
53
-
##### Uninstall `@cloudflare/workers-types`
53
+
To ensure that your types are always up-to-date, make sure to run `wrangler types` after any changes to your config file.
54
54
55
-
<Tabs> <TabItemlabel="npm">
55
+
:::
56
56
57
-
```sh
58
-
npm uninstall @cloudflare/workers-types
59
-
```
57
+
<h3id="migrating">
58
+
Migrating from `@cloudflare/workers-types` to `wrangler types`
59
+
</h3>
60
60
61
-
</TabItem> <TabItemlabel="yarn">
61
+
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.
62
62
63
-
```sh
64
-
yarn remove @cloudflare/workers-types
65
-
```
63
+
:::note
66
64
67
-
</TabItem> <TabItemlabel="pnpm">
65
+
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.
##### Update your `tsconfig.json` to include the generated types
77
+
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`.
78
+
79
+
You can now remove any imports from `@cloudflare/workers-types` in your Worker code.
#### 3. Make sure your `tsconfig.json` includes the generated types
84
88
85
89
```json
86
90
{
87
91
"compilerOptions": {
88
-
"types": ["./.wrangler/types/runtime"]
92
+
"types": ["worker-configuration.d.ts"]
89
93
}
90
94
}
91
95
```
92
96
93
97
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.
94
98
95
-
##### Update your scripts and CI pipelines
99
+
#### 4. Add @types/node if you are using [`nodejs_compat`](/workers/runtime-apis/nodejs/) (Optional)
100
+
101
+
If you are using the `nodejs_compat` compatibility flag, you should also install `@types/node`.
102
+
103
+
<PackageManagerstype="add"pkg="@types/node" />
104
+
105
+
Then add this to your `tsconfig.json`.
106
+
107
+
```json
108
+
{
109
+
"compilerOptions": {
110
+
"types": ["worker-configuration.d.ts", "node"]
111
+
}
112
+
}
113
+
```
114
+
115
+
#### 5. Update your scripts and CI pipelines
96
116
97
-
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.
117
+
Regardless of your specific framework or build tools, you should run the `wrangler types` command before any tasks that rely on TypeScript.
98
118
99
-
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:
119
+
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:
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:
132
+
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:
112
133
113
134
<Tabs> <TabItemlabel="npm">
114
135
@@ -136,26 +157,6 @@ In CI, you may have separate build and test commands. It is best practice to run
136
157
137
158
</TabItem> </Tabs>
138
159
139
-
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.
140
-
141
-
### Known issues
142
-
143
-
#### Transitive loading of `@types/node` overrides `@cloudflare/workers-types`
144
-
145
-
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.
146
-
147
-
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:
148
-
149
-
```json
150
-
{
151
-
"overrides": {
152
-
"@types/node": "20.8.3"
153
-
}
154
-
}
155
-
```
156
-
157
-
For more information, refer to [this GitHub issue](https://github.com/cloudflare/workerd/issues/1298).
Copy file name to clipboardExpand all lines: src/content/docs/workers/observability/logs/logpush.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,7 @@ Workers Trace Events Logpush is not available for zones on the [Cloudflare China
24
24
## Verify your Logpush access
25
25
26
26
:::note[Wrangler version]
27
-
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/).
27
+
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/).
28
28
:::
29
29
30
30
To configure a Logpush job, verify that your Cloudflare account role can use Logpush. To check your role:
Copy file name to clipboardExpand all lines: src/content/docs/workers/observability/logs/workers-logs.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,7 @@ To send logs to a third party, use [Workers Logpush](/workers/observability/logs
24
24
## Enable Workers Logs
25
25
26
26
:::note[Wrangler version]
27
-
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/).
27
+
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/).
28
28
:::
29
29
30
30
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.
![hyperlint-ai[bot]](https://avatars.githubusercontent.com/in/718456?v=4&size=40){kind=avatar}
0 commit comments