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
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 also 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`, you should also 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/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 accessed on the `env` object.
29
+
4. Any [module rules](/workers/wrangler/configuration/#inheritable-keys) 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.toml`, 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 onlly 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 provides better support for combinations of [compatibility date](https://github.com/cloudflare/workerd/tree/main/npm/workers-types#compatibility-dates) and `compatibility flags`. Note that there are no plans to stop publishing the `@cloudflare/workers-types` package.
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
72
79
-
</TabItem> </Tabs>
73
+
You can now remove any imports from `@cloudflare/workers-types` in your Worker code.
This will generate a `.d.ts` file, saved to `.wrangler/types/runtime.d.ts` by default.
79
+
:::
88
80
89
-
##### Update your `tsconfig.json`to include the generated types
81
+
####3. Make sure your `tsconfig.json`includes the generated types
90
82
91
83
```json
92
84
{
93
85
"compilerOptions": {
94
-
"types": ["./.wrangler/types/runtime"]
86
+
"types": ["worker-configuration.d.ts"]
95
87
}
96
88
}
97
89
```
98
90
99
91
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.
100
92
101
-
##### Update your scripts and CI pipelines
93
+
####4. Add @types/node if you are using [`nodejs_compat`](/workers/runtime-apis/nodejs/) (Optional)
102
94
103
-
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.
95
+
If you are using the `nodejs_compat` compatibility flag, you should also install `@types/node`.
104
96
105
-
Most projects will have existing build and development scripts 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:
97
+
<PackageManagerstype="add"pkg="@types/node" />
98
+
99
+
Then add this to your `tsconfig.json`.
100
+
101
+
```json
102
+
{
103
+
"compilerOptions": {
104
+
"types": ["worker-configuration.d.ts", "node"]
105
+
}
106
+
}
107
+
```
108
+
109
+
#### 5. Update your scripts and CI pipelines
110
+
111
+
Regardless of your specific framework or build tools, you should run the `wrangler types` command before any tasks that rely on TypeScript.
112
+
113
+
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 a separate build and test commands. It is best practice to run `wrangler types --experimental-include-runtime` before other CI commands. For example:
126
+
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:
118
127
119
128
<Tabs> <TabItemlabel="npm">
120
129
@@ -150,8 +159,6 @@ In CI, you may have a separate build and test commands. It is best practice to r
150
159
151
160
</TabItem> </Tabs>
152
161
153
-
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.
154
-
155
162
### Known issues
156
163
157
164
#### Transitive loading of `@types/node` overrides `@cloudflare/workers-types`
@@ -176,3 +183,4 @@ For more information, refer to [this GitHub issue](https://github.com/cloudflare
Generate types from bindings and module rulesin configuration.
2259
+
Generate types based on your Worker configuration, including `Env` types based on your bindings, module rules, and [runtime types](/workers/language/typescript/) based on the`compatibility_date` and `compatibility_flags`in your [config file](/workers/wrangler/configuration/).
2260
2260
2261
2261
```txt
2262
2262
wrangler types [<PATH>] [OPTIONS]
2263
2263
```
2264
2264
2265
2265
:::note
2266
2266
2267
-
The `--experimental-include-runtime` flag dynamically generates runtime types according to the `compatibility_date` and `compatibility_flags` defined in your [config file](/workers/wrangler/configuration/).
2268
-
2269
-
It is a replacement for the [`@cloudflare/workers-types` package](https://www.npmjs.com/package/@cloudflare/workers-types), so that package, if installed, should be uninstalled to avoid any potential conflict.
2270
-
2271
-
After running the command, you must add the path of the generated runtime types file to the [`compilerOptions.types` field](https://www.typescriptlang.org/tsconfig/#types) in your project's [tsconfig.json](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file.
2272
-
2273
-
You may use the shorthand `--x-include-runtime` flag in place of `--experimental-include-runtime` anywhere it is mentioned.
2274
-
2275
-
The minimum required Wrangler version to use this command is 3.66.0.
- Whether to generate runtime types based on the`compatibility_date` and `compatibility_flags` in your [config file](/workers/wrangler/configuration/).
- Control the types that Wrangler generates for `vars` bindings.
2283
+
- If `true`, (the default) Wrangler generates literal and union types for bindings (e.g. `myVar: 'my dev variable' | 'my prod variable'`).
2284
+
- If `false`, Wrangler generates generic types (e.g. `myVar: string`). This is useful when variables change frequently, especially when working across multiple environments.
If you are running a version of Wrangler that is greater than `3.66.0` but below `4.0.0`, you will need to include the `--experimental-include-runtime` flag. During its experimental release, runtime types were output to a separate file (`.wrangler/types/runtime.d.ts` by default). If you have an older version of Wrangler, you can access runtime types through the `@cloudflare/workers-types` package.
0 commit comments