diff --git a/src/content/changelog/workers/2025-03-13-wrangler-v4.mdx b/src/content/changelog/workers/2025-03-13-wrangler-v4.mdx new file mode 100644 index 000000000000000..7cfebc29a45924c --- /dev/null +++ b/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-03-13T09:00:00Z +--- + +import { PackageManagers } from "~/components"; + +We've released the next major version of [Wrangler](/workers/wrangler/), the CLI for Cloudflare Workers — `wrangler@4.0.0`. 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](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. diff --git a/src/content/docs/pages/framework-guides/deploy-a-hono-site.mdx b/src/content/docs/pages/framework-guides/deploy-a-hono-site.mdx index b1da2a0100c0924..d4e42df389bd42f 100644 --- a/src/content/docs/pages/framework-guides/deploy-a-hono-site.mdx +++ b/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" }, ``` diff --git a/src/content/docs/pages/functions/typescript.mdx b/src/content/docs/pages/functions/typescript.mdx index d5fbcd9feedaa82..e6e3f0016883dba 100644 --- a/src/content/docs/pages/functions/typescript.mdx +++ b/src/content/docs/pages/functions/typescript.mdx @@ -5,15 +5,19 @@ 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 -``` + -Then configure the runtime types by creating a `functions/tsconfig.json` file: +Then configure the types by creating a `functions/tsconfig.json` file: ```json { @@ -21,11 +25,13 @@ Then configure the runtime types by creating a `functions/tsconfig.json` file: "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 = 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). + +::: diff --git a/src/content/docs/workers/configuration/multipart-upload-metadata.mdx b/src/content/docs/workers/configuration/multipart-upload-metadata.mdx index db3b044f54fcfc8..a66222a58afe0aa 100644 --- a/src/content/docs/workers/configuration/multipart-upload-metadata.mdx +++ b/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` - - * Usage model to apply to invocations, only allowed value is `standard`. - - ## Additional attributes: [Workers Script Upload API](/api/resources/workers/subresources/scripts/methods/update/) diff --git a/src/content/docs/workers/languages/javascript/index.mdx b/src/content/docs/workers/languages/javascript/index.mdx index 2cecc8ce07d82a3..e1386eb7eadcde0 100644 --- a/src/content/docs/workers/languages/javascript/index.mdx +++ b/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. diff --git a/src/content/docs/workers/languages/typescript/index.mdx b/src/content/docs/workers/languages/typescript/index.mdx index 68e7a00f9f1cb92..2bf5240648ada82 100644 --- a/src/content/docs/workers/languages/typescript/index.mdx +++ b/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) +

+ Generate types that match your Worker's configuration +

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 -``` + -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" -``` + -**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. - +::: -```sh -npm uninstall @cloudflare/workers-types -``` +

+ Migrating from `@cloudflare/workers-types` to `wrangler types` +

- +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 - +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 -``` +::: - +#### 1. Uninstall `@cloudflare/workers-types` -##### Generate runtime types using wrangler + -```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. + -##### 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 + + + +::: + +#### 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`. + + + +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: @@ -136,26 +157,6 @@ In CI, you may have separate build and test commands. It is best practice to run -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/node@20.8.4` 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) diff --git a/src/content/docs/workers/observability/logs/logpush.mdx b/src/content/docs/workers/observability/logs/logpush.mdx index 0ab799f17042993..0c072f3f75a8374 100644 --- a/src/content/docs/workers/observability/logs/logpush.mdx +++ b/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: diff --git a/src/content/docs/workers/observability/logs/workers-logs.mdx b/src/content/docs/workers/observability/logs/workers-logs.mdx index a8f6fb07c48aeba..e4e4e9e4107ac96 100644 --- a/src/content/docs/workers/observability/logs/workers-logs.mdx +++ b/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. diff --git a/src/content/docs/workers/tutorials/github-sms-notifications-using-twilio/index.mdx b/src/content/docs/workers/tutorials/github-sms-notifications-using-twilio/index.mdx index afdd3b7af06c1b9..08e6d566890b345 100644 --- a/src/content/docs/workers/tutorials/github-sms-notifications-using-twilio/index.mdx +++ b/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 diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx index 2163ad5162b4267..7f8bedfc98c835d 100644 --- a/src/content/docs/workers/wrangler/commands.mdx +++ b/src/content/docs/workers/wrangler/commands.mdx @@ -7,19 +7,24 @@ head: description: Create, develop, and deploy your Cloudflare Workers with Wrangler commands. --- -import { TabItem, Tabs, Render, Type, MetaInfo, WranglerConfig } from "~/components"; +import { + TabItem, + Tabs, + Render, + Type, + MetaInfo, + WranglerConfig, +} from "~/components"; Wrangler offers a number of commands to manage your Cloudflare Workers. - [`docs`](#docs) - Open this page in your default browser. - [`init`](#init) - Create a new project from a variety of web frameworks and templates. -- [`generate`](#generate) - Create a Wrangler project using an existing [Workers template](https://github.com/cloudflare/worker-template). - [`d1`](#d1) - Interact with D1. - [`vectorize`](#vectorize) - Interact with Vectorize indexes. - [`hyperdrive`](#hyperdrive) - Manage your Hyperdrives. - [`deploy`](#deploy) - Deploy your Worker to Cloudflare. - [`dev`](#dev) - Start a local server for developing your Worker. -- [`publish`](#publish) - Publish your Worker to Cloudflare. - [`delete`](#delete-2) - Delete your Worker from Cloudflare. - [`kv namespace`](#kv-namespace) - Manage Workers KV namespaces. - [`kv key`](#kv-key) - Manage key-value pairs within a Workers KV namespace. @@ -152,29 +157,6 @@ wrangler init [] [OPTIONS] --- -## `generate` - -:::note - -This command has been deprecated as of [Wrangler v3](/workers/wrangler/migration/update-v2-to-v3/) and will be removed in a future version. - -::: - -Create a new project using an existing [Workers template](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker). - -```txt -wrangler generate [] [TEMPLATE] -``` - -- `NAME` - - The name of the Workers project. This is both the directory name and `name` property in the generated [Wrangler configuration](/workers/wrangler/configuration/). -- `TEMPLATE` - - The URL of a GitHub template, with a default [worker-template](https://github.com/cloudflare/worker-template). Browse a list of available templates on the [cloudflare/workers-sdk](https://github.com/cloudflare/workers-sdk/tree/main/templates#usage) repository. - - - ---- - ## `d1` Interact with Cloudflare's D1 service. @@ -469,8 +451,6 @@ As of Wrangler v3.2.0, `wrangler dev` is supported by any Linux distributions pr - Host to act as origin in local mode, defaults to `dev.host` or route. - `--assets` - Folder of static assets to be served. Replaces [Workers Sites](/workers/configuration/sites/). Visit [assets](/workers/static-assets/) for more information. -- `--legacy-assets` - - Folder of static assets to be served. - `--site` - Folder of static assets for Workers Sites. :::caution @@ -494,8 +474,6 @@ As of Wrangler v3.2.0, `wrangler dev` is supported by any Linux distributions pr - Path to a custom `tsconfig.json` file. - `--minify` - Minify the Worker. -- `--node-compat` - - Enable Node.js compatibility. - `--persist-to` - Specify directory to use for local persistence. - `--remote` @@ -547,8 +525,6 @@ None of the options for this command are required. Also, many can be set in your - Use the latest version of the Workers runtime. - `--assets` - Folder of static assets to be served. Replaces [Workers Sites](/workers/configuration/sites/). Visit [assets](/workers/static-assets/) for more information. -- `--legacy-assets` - - Folder of static assets to be served. - `--site` - Folder of static assets for Workers Sites. :::caution @@ -575,8 +551,6 @@ None of the options for this command are required. Also, many can be set in your - Path to a custom `tsconfig.json` file. - `--minify` - Minify the bundled Worker before deploying. -- `--node-compat` - - Enable node.js compatibility. - `--dry-run` - Compile a project without actually deploying to live servers. Combined with `--outdir`, this is also useful for testing the output of `npx wrangler deploy`. It also gives developers a chance to upload our generated sourcemap to a service like Sentry, so that errors from the Worker can be mapped against source code, but before the service goes live. - `--keep-vars` @@ -589,22 +563,6 @@ None of the options for this command are required. Also, many can be set in your --- -## `publish` - -Publish your Worker to Cloudflare. - -```txt -wrangler publish [OPTIONS] -``` - -:::note - -This command has been deprecated as of v3 in favor of [`wrangler deploy`](#deploy). It will be removed in v4. - -::: - ---- - ## `delete` Delete your Worker and all associated Cloudflare developer platform resources. @@ -1140,22 +1098,6 @@ Your site is deployed to `.pages.dev`. If you do not provide the ` ::: -### `publish` - -Publish a directory of static assets as a Pages deployment. - -```txt -wrangler pages publish [] [OPTIONS] -``` - - - -:::note - -This command has been deprecated as of v3 in favor of [`wrangler pages deploy`](#deploy-1). It will be removed in v4. - -::: - ### `secret put` Create or update a secret for a Pages project. @@ -1841,6 +1783,7 @@ wrangler cert upload certificate-authority --ca-cert [OPTIONS] ``` - `--ca-cert` + - A path to the Certificate Authority (CA) chain certificate to upload. - `--name` @@ -1924,7 +1867,7 @@ Deleted certificate 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d successfully ## `types` -Generate types from bindings and module rules in configuration. +Generate types based on your Worker configuration, including `Env` types based on your bindings, module rules, and [runtime types](/workers/languages/typescript/) based on the`compatibility_date` and `compatibility_flags` in your [config file](/workers/wrangler/configuration/). ```txt wrangler types [] [OPTIONS] @@ -1932,33 +1875,24 @@ wrangler types [] [OPTIONS] :::note -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/). - -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. - -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. - -You may use the shorthand `--x-include-runtime` flag in place of `--experimental-include-runtime` anywhere it is mentioned. - -The minimum required Wrangler version to use this command is 3.66.0. + ::: - `PATH` - - The path to where **the `Env` types** for your Worker will be written. + - The path to where types for your Worker will be written. - The path must have a `d.ts` extension. - `--env-interface` - The name of the interface to generate for the environment object. - Not valid if the Worker uses the Service Worker syntax. -- `--experimental-include-runtime` - - The path to where the **runtime types** file will be written. - - Leave the path blank to use the default option, e.g. `npx wrangler types --x-include-runtime` - - A custom path must be relative to the project root, e.g. `./my-runtime-types.d.ts` - - A custom path must have a `d.ts` extension. +- `--include-runtime` + - Whether to generate runtime types based on the`compatibility_date` and `compatibility_flags` in your [config file](/workers/wrangler/configuration/). +- `--include-env` + - Whether to generate `Env` types based on your Worker bindings. - `--strict-vars` - Control the types that Wrangler generates for `vars` bindings. - - If `true`, (the default) Wrangler generates literal and union types for bindings (e.g. `myEnv: 'my dev variable' | 'my prod variable'`). - - If `false`, Wrangler generates generic types (e.g. `myEnv: string`). This is useful when variables change frequently, especially when working across multiple environments. + - If `true`, (the default) Wrangler generates literal and union types for bindings (e.g. `myVar: 'my dev variable' | 'my prod variable'`). + - If `false`, Wrangler generates generic types (e.g. `myVar: string`). This is useful when variables change frequently, especially when working across multiple environments. diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index bcdcb64b898b736..2dc256b2c9a3243 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -167,12 +167,6 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d - Minify the Worker script before uploading. -- `node_compat` - - - Deprecated — Instead, [enable the `nodejs_compat` compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag), which enables both built-in Node.js APIs, and adds polyfills as necessary. - Setting `node_compat = true` will add polyfills for Node.js built-in modules and globals to your Worker's code, when bundled with Wrangler. - This is powered by `@esbuild-plugins/node-globals-polyfill` which in itself is powered by [rollup-plugin-node-polyfills](https://github.com/ionic-team/rollup-plugin-node-polyfills/). - - `logpush` - Enables Workers Trace Events Logpush for a Worker. Any scripts with this property will automatically get picked up by the Workers Logpush job configured for your account. Defaults to `false`. Refer to [Workers Logpush](/workers/observability/logs/logpush/). @@ -188,12 +182,6 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d * `assets` - Configures static assets that will be served. Refer to [Assets](/workers/static-assets/binding/) for more details. -### Usage model - -As of March 1, 2024 the [usage model](/workers/platform/pricing/#workers) configured in your Worker's configuration file will be ignored. The [Standard](/workers/platform/pricing/#example-pricing-standard-usage-model) usage model applies. - -Some Workers Enterprise customers maintain the ability to change usage models. Your usage model must be configured through the Cloudflare dashboard by going to **Workers & Pages** > select your Worker > **Settings** > **Usage Model**. - ## Non-inheritable keys Non-inheritable keys are configurable at the top-level, but cannot be inherited by environments and must be specified for each environment. diff --git a/src/content/docs/workers/wrangler/deprecations.mdx b/src/content/docs/workers/wrangler/deprecations.mdx index 1cfe92f9a6f3d4d..e8fe04ab05a97ce 100644 --- a/src/content/docs/workers/wrangler/deprecations.mdx +++ b/src/content/docs/workers/wrangler/deprecations.mdx @@ -9,6 +9,16 @@ description: The differences between Wrangler versions, specifically Review the difference between Wrangler versions, specifically deprecations and breaking changes. +## Wrangler v4 + +### Workers Sites + +Usage of [Workers Sites](/workers/wrangler/configuration/#workers-sites) is deprecated. Instead, we recommend migrating to [Workers Static Assets](/workers/static-assets/). Support for using Workers Sites with Wrangler will be removed in a future version of Wrangler. + +### Service environments + +Usage of [Service Environments](https://blog.cloudflare.com/introducing-worker-services/#services-have-environments), enabled via the `legacy_env` property in Wrangler config, is deprecated. Instead, we recommend migrating to [Wrangler Environments](/workers/wrangler/configuration/#environments). Support for using Service Environments with Wrangler will be removed in a future version of Wrangler. + ## Wrangler v3 ### Deprecated commands diff --git a/src/content/docs/workers/wrangler/install-and-update.mdx b/src/content/docs/workers/wrangler/install-and-update.mdx index c043786cbab6bfd..5c17966976e8f15 100644 --- a/src/content/docs/workers/wrangler/install-and-update.mdx +++ b/src/content/docs/workers/wrangler/install-and-update.mdx @@ -14,7 +14,16 @@ Wrangler is a command-line tool for building with Cloudflare developer products. ## Install Wrangler -To install [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler), ensure you have [Node.js](https://nodejs.org/en/) and [npm](https://docs.npmjs.com/getting-started) installed, preferably using a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm). Using a version manager helps avoid permission issues and allows you to change Node.js versions. Wrangler requires a Node version of `16.17.0` or later. +To install [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler), ensure you have [Node.js](https://nodejs.org/en/) and [npm](https://docs.npmjs.com/getting-started) installed, preferably using a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm). Using a version manager helps avoid permission issues and allows you to change Node.js versions. + +
+Wrangler System Requirements + +We support running the Wrangler CLI with the [Current, Active, and Maintenance](https://nodejs.org/en/about/previous-releases) versions of Node.js. Your Worker will always be executed in `workerd`, the open source Cloudflare Workers runtime. + +Wrangler is only supported on macOS 13.5+, Windows 11, and Linux distros that support glib 2.35. This follows [`workerd`'s OS support policy](https://github.com/cloudflare/workerd?tab=readme-ov-file#running-workerd). + +
Wrangler is installed locally into each of your projects. This allows you and your team to use the same Wrangler version, control Wrangler versions for each project, and roll back to an earlier version of Wrangler, if needed. diff --git a/src/content/docs/workers/wrangler/migration/update-v2-to-v3.mdx b/src/content/docs/workers/wrangler/migration/update-v2-to-v3.mdx index c70685cae18c062..15bcd7d90746f7e 100644 --- a/src/content/docs/workers/wrangler/migration/update-v2-to-v3.mdx +++ b/src/content/docs/workers/wrangler/migration/update-v2-to-v3.mdx @@ -2,7 +2,7 @@ title: Migrate from Wrangler v2 to v3 pcx_content_type: how-to sidebar: - order: 1 + order: 2 --- diff --git a/src/content/docs/workers/wrangler/migration/update-v3-to-v4.mdx b/src/content/docs/workers/wrangler/migration/update-v3-to-v4.mdx new file mode 100644 index 000000000000000..553be05485e9c8b --- /dev/null +++ b/src/content/docs/workers/wrangler/migration/update-v3-to-v4.mdx @@ -0,0 +1,61 @@ +--- +title: Migrate from Wrangler v3 to v4 +pcx_content_type: how-to +sidebar: + order: 1 +--- + +Wrangler v4 is a major release focused on updates to underlying systems and dependencies, along with improvements to keep Wrangler commands consistent and clear. 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. + +While many users should expect a no-op upgrade, the following sections outline the more significant changes and steps for migrating where necessary. + +### Summary of changes + +- **Updated Node.js support policy:** + Node.js v16, which reached End-of-Life in 2022, is no longer supported in Wrangler v4. Wrangler now follows Node.js's [official support lifecycle](https://nodejs.org/en/about/previous-releases). + +- **Upgraded esbuild version**: Wrangler uses [esbuild](https://esbuild.github.io/) to bundle Worker code before deploying it, and was previously pinned to esbuild v0.17.19. Wrangler v4 uses esbuild v0.24, which could impact dynamic wildcard imports. + +- **Commands default to local mode**: All commands that can run in either local or remote mode now default to local, requiring a `--remote` flag for API queries. + +- **Deprecated commands and configurations removed:** Legacy commands, flags, and configurations are removed. + +## Detailed Changes + +### Updated Node.js support policy + +Wrangler now supports only Node.js versions that align with [Node.js's official lifecycle](https://nodejs.org/en/about/previous-releases): + +- **Supported**: Current, Active LTS, Maintenance LTS +- **No longer supported:** Node.js v16 (EOL in 2022) + +Wrangler tests no longer run on v16, and users still on this version may encounter unsupported behavior. Users still using Node.js v16 must upgrade to a supported version to continue receiving support and compatibility with Wrangler. + +### Upgraded esbuild version + +Wrangler v4 upgrades esbuild from **v0.17.19** to **v0.24**, bringing improvements (such as the ability to use the `using` keyword with RPC) and changes to bundling behavior: + +- **Dynamic imports:** Wildcard imports (for example, `import('./data/' + kind + '.json')`) now automatically include all matching files in the bundle. + +Users relying on wildcard dynamic imports may see unwanted files bundled. Prior to esbuild v0.19, `import` statements with dynamic paths ( like `import('./data/' + kind + '.json')`) did not bundle all files matches the glob pattern (`*.json`) . Only files explicitly referenced or included using `find_additional_modules` were bundled. With esbuild v0.19, wildcard imports now automatically bundle all files matching the glob pattern. This could result in unwanted files being bundled, so users might want to avoid wildcard dynamic imports and use explicit imports instead. + +### Commands default to local mode + +All commands now run in **local mode by default.** Wrangler has many commands for accessing resources like KV and R2, but the commands were previously inconsistent in whether they ran in a local or remote environment. For example, D1 defaulted to querying a local datastore, and required the `--remote` flag to query via the API. KV, on the other hand, previously defaulted to querying via the API (implicitly using the `--remote` flag) and required a `--local` flag to query a local datastore. In order to make the behavior consistent across Wrangler, each command now uses the `--local` flag by default, and requires an explicit `--remote` flag to query via the API. + +For example: + +- **Previous Behavior (Wrangler v3):** `wrangler kv get` queried remotely by default. +- **New Behavior (Wrangler v4):** `wrangler kv get` queries locally unless `--remote` is specified. + +Those using `wrangler kv key` and/or `wrangler r2 object` commands to query or write to their data store will need to add the `--remote` flag in order to replicate previous behavior. + +### Deprecated commands and configurations removed + +All previously deprecated features in [Wrangler v2](https://developers.cloudflare.com/workers/wrangler/deprecations/#wrangler-v2) and in [Wrangler v3](https://developers.cloudflare.com/workers/wrangler/deprecations/#wrangler-v3) are now removed. Additionally, the following features that were deprecated during the Wrangler v3 release are also now removed: + +- Legacy Assets (using `wrangler dev/deploy --legacy-assets` or the `legacy_assets` config file property). Instead, we recommend you [migrate to Workers assets](https://developers.cloudflare.com/workers/static-assets/). +- Legacy Node.js compatibility (using `wrangler dev/deploy --node-compat` or the `node_compat` config file property). Instead, use the [`nodejs_compat` compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs). This includes the functionality from legacy `node_compat` polyfills and natively implemented Node.js APIs. +- `wrangler version`. Instead, use `wrangler --version` to check the current version of Wrangler. +- `getBindingsProxy()` (via `import { getBindingsProxy } from "wrangler"`). Instead, use the [`getPlatformProxy()` API](https://developers.cloudflare.com/workers/wrangler/api/#getplatformproxy), which takes exactly the same arguments. +- `usage_model`. This no longer has any effect, after the [rollout of Workers Standard Pricing](https://blog.cloudflare.com/workers-pricing-scale-to-zero/). diff --git a/src/content/docs/workers/wrangler/migration/v1-to-v2/index.mdx b/src/content/docs/workers/wrangler/migration/v1-to-v2/index.mdx index c2ed5ec6cc2c480..4f9e78b58d62cf4 100644 --- a/src/content/docs/workers/wrangler/migration/v1-to-v2/index.mdx +++ b/src/content/docs/workers/wrangler/migration/v1-to-v2/index.mdx @@ -2,7 +2,7 @@ title: Migrate from Wrangler v1 to v2 pcx_content_type: how-to sidebar: - order: 1 + order: 3 group: hideIndex: true --- diff --git a/src/content/partials/workers/wrangler-commands/d1.mdx b/src/content/partials/workers/wrangler-commands/d1.mdx index 1c1bb3ef1b6671f..e4f40ecd924aeaa 100644 --- a/src/content/partials/workers/wrangler-commands/d1.mdx +++ b/src/content/partials/workers/wrangler-commands/d1.mdx @@ -87,8 +87,6 @@ You must provide either `--command` or `--file` for this command to run successf - Return output as JSON rather than a table. - `--preview` - Execute commands/files against a preview D1 database (as defined by `preview_database_id` in the [Wrangler configuration file](/workers/wrangler/configuration/#d1-databases)). -- `--batch-size` - - Number of queries to send in a single batch. @@ -153,84 +151,6 @@ wrangler d1 time-travel info [OPTIONS] - `--json` b - Return output as JSON rather than a table. - - -:::caution - -This command only works on databases created during D1's alpha period. You can check which version your database uses with `wrangler d1 info `. - -This command will not work on databases that are created during the beta period, or after general availability (GA). Refer to [Time Travel](/d1/reference/time-travel/) in the D1 documentation for more information on D1's approach to backup and restores for databases created during the beta/GA period. -::: - -Initiate a D1 backup. - -```txt -wrangler d1 backup create -``` - -- `DATABASE_NAME` - - The name of the D1 database to backup. - - - -:::caution - -This command only works on databases created during D1's alpha period. You can check which version your database uses with `wrangler d1 info `. - -This command will not work on databases that are created during the beta period, or after general availability (GA). Refer to [Time Travel](/d1/reference/time-travel/) in the D1 documentation for more information on D1's approach to backup and restores for databases created during the beta/GA period. -::: - -List all available backups. - -```txt -wrangler d1 backup list -``` - -- `DATABASE_NAME` - - The name of the D1 database to list the backups of. - - - -:::caution - -This command only works on databases created during D1's alpha period. You can check which version your database uses with `wrangler d1 info `. - -This command will not work on databases that are created during the beta period, or after general availability (GA). Refer to [Time Travel](/d1/reference/time-travel/) in the D1 documentation for more information on D1's approach to backup and restores for databases created during the beta/GA period. -::: - -Restore a backup into a D1 database. - -```txt -wrangler d1 backup restore -``` - -- `DATABASE_NAME` - - The name of the D1 database to restore the backup into. -- `BACKUP_ID` - - The ID of the backup you wish to restore. - - - -:::caution - -This command only works on databases created during D1's alpha period. You can check which version your database uses with `wrangler d1 info `. - -This command will not work on databases that are created during the beta period, or after general availability (GA). To download existing data of a beta/GA database to your local machine refer to the `wrangler d1 export` command. Refer to [Time Travel](/d1/reference/time-travel/) in the D1 documentation for more information on D1's approach to backups for databases created during the beta/GA period. -::: - -Download existing data to your local machine. - -```txt -wrangler d1 backup download -``` - -- `DATABASE_NAME` - - The name of the D1 database you wish to download the backup of. -- `BACKUP_ID` - - The ID of the backup you wish to download. -- `--output` - - The `.sqlite3` file to write to (defaults to `'..sqlite3'`). - [OPTIONS] - Specify directory to use for local persistence (for use in combination with `--local`). - `--preview` - Execute any unapplied migrations on your preview D1 database (as defined by `preview_database_id` in the [Wrangler configuration file](/workers/wrangler/configuration/#d1-databases)). -- `--batch-size` - - Number of queries to send in a single batch. diff --git a/src/content/partials/workers/wrangler-commands/kv.mdx b/src/content/partials/workers/wrangler-commands/kv.mdx index b3d486ba070df1c..1c98e5307931c9f 100644 --- a/src/content/partials/workers/wrangler-commands/kv.mdx +++ b/src/content/partials/workers/wrangler-commands/kv.mdx @@ -192,8 +192,10 @@ This command requires a `--binding` or `--namespace-id` flag. - The timestamp, in UNIX seconds, indicating when the key-value pair should expire. - `--metadata` - Any (escaped) JSON serialized arbitrary object to a maximum of 1024 bytes. -- `--local` +- `--local` - Interact with locally persisted data. +- `--remote` + - Interact with remote storage. - `--persist-to` - Specify directory for locally persisted data. @@ -262,8 +264,10 @@ This command requires `--binding` or `--namespace-id`. - Interact with a preview namespace instead of production. - `--prefix` - Only list keys that begin with the given prefix. -- `--local` +- `--local` - Interact with locally persisted data. +- `--remote` + - Interact with remote storage. - `--persist-to` - Specify directory for locally persisted data. @@ -312,8 +316,10 @@ Exactly one of `--binding` or `--namespace-id` is required. - Interact with a preview namespace instead of production. - `--text` - Decode the returned value as a UTF-8 string. -- `--local` +- `--local` - Interact with locally persisted data. +- `--remote` + - Interact with remote storage. - `--persist-to` - Specify directory for locally persisted data. @@ -352,8 +358,10 @@ Exactly one of `--binding` or `--namespace-id` is required. - Perform on a specific environment. - `--preview` - Interact with a preview namespace instead of production. -- `--local` +- `--local` - Interact with locally persisted data. +- `--remote` + - Interact with remote storage. - `--persist-to` - Specify directory for locally persisted data. @@ -406,8 +414,10 @@ This command requires `--binding` or `--namespace-id`. - Perform on a specific environment. - `--preview` - Interact with a preview namespace instead of production. -- `--local` +- `--local` - Interact with locally persisted data. +- `--remote` + - Interact with remote storage. - `--persist-to` - Specify directory for locally persisted data. @@ -490,8 +500,10 @@ This command requires `--binding` or `--namespace-id`. - Perform on a specific environment. - `--preview` - Interact with a preview namespace instead of production. -- `--local` +- `--local` - Interact with locally persisted data. +- `--remote` + - Interact with remote storage. - `--persist-to` - Specify directory for locally persisted data. diff --git a/src/content/partials/workers/wrangler-commands/r2.mdx b/src/content/partials/workers/wrangler-commands/r2.mdx index c30b4a1a3653a85..9b6786229f7ceec 100644 --- a/src/content/partials/workers/wrangler-commands/r2.mdx +++ b/src/content/partials/workers/wrangler-commands/r2.mdx @@ -549,8 +549,10 @@ wrangler r2 object get [OPTIONS] - `OBJECT_PATH` - The source object path in the form of `{bucket}/{key}`. -- `--local` +- `--local` - Interact with locally persisted data. +- `--remote` + - Interact with remote storage. - `--persist-to` - Specify directory for locally persisted data. @@ -580,8 +582,10 @@ wrangler r2 object put [OPTIONS] - Specifies caching behavior along the request/reply chain. - `--expires` - The date and time at which the object is no longer cacheable. -- `--local` +- `--local` - Interact with locally persisted data. +- `--remote` + - Interact with remote storage. - `--persist-to` - Specify directory for locally persisted data. @@ -595,8 +599,10 @@ wrangler r2 object delete [OPTIONS] - `OBJECT_PATH` - The destination object path in the form of `{bucket}/{key}`. -- `--local` +- `--local` - Interact with locally persisted data. +- `--remote` + - Interact with remote storage. - `--persist-to` - Specify directory for locally persisted data. diff --git a/src/content/partials/workers/wrangler-commands/runtime-types.mdx b/src/content/partials/workers/wrangler-commands/runtime-types.mdx new file mode 100644 index 000000000000000..808c6bab8870bcf --- /dev/null +++ b/src/content/partials/workers/wrangler-commands/runtime-types.mdx @@ -0,0 +1,7 @@ +--- +{} +--- + +import { Type } from "~/components"; + +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.