diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b9a72970894c170..6122a660c7e851f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,9 +33,46 @@ If we require more information to address your pull request, the `more-informati
- [npm](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager#introduction-to-npm) is the recommended package manager that must be used in installing dependencies.
- The generated `package-lock.json` file must be committed to git.
+## Wrangler config
+
+If you're adding a code snippet to the docs that represents a Wrangler config file (`wrangler.toml` or `wrangler.json`) make sure you wrap it with the `` component, which ensure it's rendered as both JSON and TOML e.g.
+
+````
+
+import { WranglerConfig } from "~/components";
+
+
+
+```toml
+# Top-level configuration
+name = "my-worker"
+main = "src/index.js"
+compatibility_date = "2022-07-12"
+
+workers_dev = false
+route = { pattern = "example.org/*", zone_name = "example.org" }
+
+kv_namespaces = [
+ { binding = "", id = "" }
+]
+
+[env.staging]
+name = "my-worker-staging"
+route = { pattern = "staging.example.org/*", zone_name = "example.org" }
+
+kv_namespaces = [
+ { binding = "", id = "" }
+]
+```
+
+
+
+````
## Workers Playground
+
If you are adding a code snippet to the docs that is:
+
1. A fully contained, valid Worker (i.e. it does not require external dependencies or specific bindings)
2. Only JavaScript
@@ -58,6 +95,7 @@ export default {
};
```
````
+
would render as
diff --git a/package-lock.json b/package-lock.json
index fa799794a674763..9d3f3833169971b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -21,6 +21,7 @@
"@cloudflare/vitest-pool-workers": "^0.5.31",
"@cloudflare/workers-types": "^4.20241112.0",
"@codingheads/sticky-header": "^1.0.2",
+ "@iarna/toml": "^2.2.5",
"@iconify-json/material-symbols": "^1.2.8",
"@stoplight/json-schema-tree": "^4.0.0",
"@types/dompurify": "^3.2.0",
@@ -44,6 +45,7 @@
"he": "^1.2.0",
"instantsearch.css": "^8.5.1",
"instantsearch.js": "^4.75.4",
+ "jsonc-parser": "^3.3.1",
"lz-string": "^1.5.0",
"marked": "^15.0.2",
"mdast-util-mdx-expression": "^2.0.1",
@@ -2870,6 +2872,12 @@
"node": ">=6"
}
},
+ "node_modules/@iarna/toml": {
+ "version": "2.2.5",
+ "resolved": "https://registry.npmjs.org/@iarna/toml/-/toml-2.2.5.tgz",
+ "integrity": "sha512-trnsAYxU3xnS1gPHPyU961coFyLkh4gAD/0zQ5mymY4yOZ+CYvsPqUbOFSw0aDM4y0tV7tiFxL/1XfXPNC6IPg==",
+ "dev": true
+ },
"node_modules/@iconify-json/material-symbols": {
"version": "1.2.8",
"resolved": "https://registry.npmjs.org/@iconify-json/material-symbols/-/material-symbols-1.2.8.tgz",
@@ -4778,6 +4786,12 @@
"vscode-uri": "^2.1.2"
}
},
+ "node_modules/@vscode/emmet-helper/node_modules/jsonc-parser": {
+ "version": "2.3.1",
+ "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-2.3.1.tgz",
+ "integrity": "sha512-H8jvkz1O50L3dMZCsLqiuB2tA7muqbSg1AtGEkN0leAqGjsUzDJir3Zwr02BhqdcITPg3ei3mZ+HjMocAknhhg==",
+ "dev": true
+ },
"node_modules/@vscode/emmet-helper/node_modules/vscode-uri": {
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-2.1.2.tgz",
@@ -10077,9 +10091,9 @@
}
},
"node_modules/jsonc-parser": {
- "version": "2.3.1",
- "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-2.3.1.tgz",
- "integrity": "sha512-H8jvkz1O50L3dMZCsLqiuB2tA7muqbSg1AtGEkN0leAqGjsUzDJir3Zwr02BhqdcITPg3ei3mZ+HjMocAknhhg==",
+ "version": "3.3.1",
+ "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
+ "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
"dev": true
},
"node_modules/jsonfile": {
@@ -16567,12 +16581,6 @@
"npm": ">=7.0.0"
}
},
- "node_modules/vscode-json-languageservice/node_modules/jsonc-parser": {
- "version": "3.3.1",
- "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
- "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
- "dev": true
- },
"node_modules/vscode-jsonrpc": {
"version": "8.2.0",
"resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
diff --git a/package.json b/package.json
index cec9de8e49340ce..6857e4ba735cc14 100644
--- a/package.json
+++ b/package.json
@@ -39,6 +39,7 @@
"@cloudflare/workers-types": "^4.20241112.0",
"@codingheads/sticky-header": "^1.0.2",
"@iconify-json/material-symbols": "^1.2.8",
+ "@iarna/toml": "^2.2.5",
"@stoplight/json-schema-tree": "^4.0.0",
"@types/dompurify": "^3.2.0",
"@types/hast": "^3.0.4",
@@ -61,6 +62,7 @@
"he": "^1.2.0",
"instantsearch.css": "^8.5.1",
"instantsearch.js": "^4.75.4",
+ "jsonc-parser": "^3.3.1",
"lz-string": "^1.5.0",
"marked": "^15.0.2",
"mdast-util-mdx-expression": "^2.0.1",
diff --git a/src/components/WranglerConfig.astro b/src/components/WranglerConfig.astro
new file mode 100644
index 000000000000000..c688153ab527cd4
--- /dev/null
+++ b/src/components/WranglerConfig.astro
@@ -0,0 +1,54 @@
+---
+import { parse } from "node-html-parser";
+import { Code, Tabs, TabItem } from "@astrojs/starlight/components";
+import TOML from "@iarna/toml";
+import { parse as jsoncParse } from "jsonc-parser";
+
+const slot = await Astro.slots.render("default");
+
+const html = parse(slot);
+
+const copy = html.querySelector("div.copy > button");
+
+if (!copy) {
+ throw new Error(
+ `[WranglerConfig] Unable to find copy button in rendered code block HTML.`,
+ );
+}
+
+let code = copy.attributes["data-code"];
+
+if (!code) {
+ throw new Error(
+ `[WranglerConfig] Unable to find data-code attribute on copy button.`,
+ );
+}
+
+code = code.replace(/\u007f/g, "\n");
+
+const language =
+ html.querySelector("[data-language]")?.attributes["data-language"];
+
+if (!language) {
+ throw new Error(`[WranglerConfig] Unable to find data-language.`);
+}
+
+let toml, json;
+
+if (language === "toml") {
+ toml = code;
+ json = JSON.stringify(TOML.parse(code), null, 2);
+} else {
+ json = code;
+ toml = TOML.stringify(jsoncParse(code));
+}
+---
+
+
+
+ queue string
@@ -53,6 +59,10 @@ To produce to a queue, set up a binding in your `wrangler.toml` file. These opti
To consume messages from one or more queues, set up a binding in your `wrangler.toml` file. These options should be used when a Worker wants to receive messages from a queue.
+
+
+
+
```toml
[[queues.consumers]]
queue = "my-queue"
@@ -62,6 +72,8 @@ To consume messages from one or more queues, set up a binding in your `wrangler.
dead_letter_queue = "my-queue-dlq"
```
+
+
Refer to [Limits](/queues/platform/limits) to review the maximum values for each of these options.
diff --git a/src/content/docs/queues/configuration/consumer-concurrency.mdx b/src/content/docs/queues/configuration/consumer-concurrency.mdx
index eb4991bfe92523e..e23d881d8ddfce1 100644
--- a/src/content/docs/queues/configuration/consumer-concurrency.mdx
+++ b/src/content/docs/queues/configuration/consumer-concurrency.mdx
@@ -84,12 +84,18 @@ Ensure you are using the latest version of [wrangler](/workers/wrangler/install-
To set a fixed maximum number of concurrent consumer invocations for a given queue, configure a `max_concurrency` in your `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[queues.consumers]]
queue = "my-queue"
max_concurrency = 1
```
+
+
To remove the limit, remove the `max_concurrency` setting from the `[[queues.consumers]]` configuration for a given queue and call `npx wrangler deploy` to push your configuration update.
{/* Not yet available but will be very soon
diff --git a/src/content/docs/queues/configuration/dead-letter-queues.mdx b/src/content/docs/queues/configuration/dead-letter-queues.mdx
index ffb5899b29ddbb5..cdfe6d16253c847 100644
--- a/src/content/docs/queues/configuration/dead-letter-queues.mdx
+++ b/src/content/docs/queues/configuration/dead-letter-queues.mdx
@@ -11,12 +11,18 @@ With Cloudflare Queues, a Dead Letter Queue is defined within your [consumer con
For example, the following consumer configuration would send messages to our DLQ named `"my-other-queue"` after retrying delivery (by default, 3 times):
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[queues.consumers]]
queue = "my-queue"
dead_letter_queue = "my-other-queue"
```
+
+
You can also configure a DLQ when creating a consumer from the command-line using `wrangler`:
```sh
diff --git a/src/content/docs/queues/configuration/pull-consumers.mdx b/src/content/docs/queues/configuration/pull-consumers.mdx
index 10695fc6847a7f5..47f6b01188e2cce 100644
--- a/src/content/docs/queues/configuration/pull-consumers.mdx
+++ b/src/content/docs/queues/configuration/pull-consumers.mdx
@@ -40,6 +40,10 @@ You can enable HTTP pull or change a queue from push-based to pull-based via `wr
A HTTP consumer can be configured in `wrangler.toml` by setting `type = "http_pull"` in the consumer configuration:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[queues.consumers]]
# Required
@@ -51,6 +55,8 @@ max_retries = 5
dead_letter_queue = "SOME-OTHER-QUEUE"
```
+
+
Omitting the `type` property will default the queue to push-based.
### wrangler CLI
@@ -247,28 +253,28 @@ Queues aims to be permissive when it comes to lease IDs: if a consumer acknowled
{/* */}
+ --> */}
## Content types
diff --git a/src/content/docs/queues/examples/publish-to-a-queue-over-http.mdx b/src/content/docs/queues/examples/publish-to-a-queue-over-http.mdx
index 0d0d5ab8e02a884..7753c6f9c7225ce 100644
--- a/src/content/docs/queues/examples/publish-to-a-queue-over-http.mdx
+++ b/src/content/docs/queues/examples/publish-to-a-queue-over-http.mdx
@@ -21,6 +21,10 @@ This allows you to write to a Queue from any service or programming language tha
Configure your `wrangler.toml` file as follows:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "my-worker"
@@ -30,6 +34,8 @@ name = "my-worker"
```
+
+
### 1. Create a shared secret
Before you deploy the Worker, you need to create a [secret](/workers/configuration/secrets/) that you can use as a shared secret. A shared secret is a secret that both the client uses to authenticate and the server (your Worker) matches against for authentication.
diff --git a/src/content/docs/queues/examples/send-errors-to-r2.mdx b/src/content/docs/queues/examples/send-errors-to-r2.mdx
index d318a1fdb123a74..c8f3aa93d71cab8 100644
--- a/src/content/docs/queues/examples/send-errors-to-r2.mdx
+++ b/src/content/docs/queues/examples/send-errors-to-r2.mdx
@@ -13,6 +13,10 @@ description: Example of how to use Queues to batch data and store it in an R2 bu
The following Worker will catch JavaScript errors and send them to a queue. The same Worker will receive those errors in batches and store them to a log file in an R2 bucket.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "my-worker"
@@ -30,6 +34,8 @@ name = "my-worker"
binding = "ERROR_BUCKET"
```
+
+
```ts
type Environment = {
readonly ERROR_QUEUE: Queue;
diff --git a/src/content/docs/queues/examples/use-queues-with-durable-objects.mdx b/src/content/docs/queues/examples/use-queues-with-durable-objects.mdx
index 3c420b8009d766f..79ccb57415ebfc4 100644
--- a/src/content/docs/queues/examples/use-queues-with-durable-objects.mdx
+++ b/src/content/docs/queues/examples/use-queues-with-durable-objects.mdx
@@ -20,6 +20,10 @@ Prerequisites:
Configure your `wrangler.toml` file as follows:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "my-worker"
@@ -37,6 +41,8 @@ tag = "v1"
new_classes = ["YourDurableObject"]
```
+
+
The following Worker script:
1. Creates a Durable Object stub, or retrieves an existing one based on a userId.
diff --git a/src/content/docs/queues/get-started.mdx b/src/content/docs/queues/get-started.mdx
index dbeb13aaf2ceecf..d04392af57517c9 100644
--- a/src/content/docs/queues/get-started.mdx
+++ b/src/content/docs/queues/get-started.mdx
@@ -70,12 +70,18 @@ To expose your queue to the code inside your Worker, you need to connect your qu
To create a binding, open your newly generated `wrangler.toml` configuration file and add the following:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[queues.producers]]
queue = "MY-QUEUE-NAME"
binding = "MY_QUEUE"
```
+
+
Replace `MY-QUEUE-NAME` with the name of the queue you created in [step 2](/queues/get-started/#2-create-a-queue). Next, replace `MY_QUEUE` with the name you want for your `binding`. The binding must be a valid JavaScript variable name. This is the variable you will use to reference this queue in your Worker.
### Write your producer Worker
@@ -184,6 +190,10 @@ Each queue can only have one consumer Worker connected to it. If you try to conn
To connect your queue to your consumer Worker, open your `wrangler.toml` file and add this to the bottom:
+
+
+
+
```toml
[[queues.consumers]]
queue = ""
@@ -193,6 +203,8 @@ To connect your queue to your consumer Worker, open your `wrangler.toml` file an
max_batch_timeout = 5 # optional: defaults to 5 seconds
```
+
+
Replace `MY-QUEUE-NAME` with the queue you created in [step 2](/queues/get-started/#2-create-a-queue).
In your consumer Worker, you are using queues to auto batch messages using the `max_batch_size` option and the `max_batch_timeout` option. The consumer Worker will receive messages in batches of `10` or every `5` seconds, whichever happens first.
diff --git a/src/content/docs/queues/reference/how-queues-works.mdx b/src/content/docs/queues/reference/how-queues-works.mdx
index eefb00a7f59f1be..e2b01267e6ee4f2 100644
--- a/src/content/docs/queues/reference/how-queues-works.mdx
+++ b/src/content/docs/queues/reference/how-queues-works.mdx
@@ -137,6 +137,10 @@ export default {
You then connect that consumer to a queue with `wrangler queues consumer ` or by defining a `[[queues.consumers]]` configuration in your `wrangler.toml` manually:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[queues.consumers]]
queue = ""
@@ -144,6 +148,8 @@ You then connect that consumer to a queue with `wrangler queues consumer
+
Importantly, each queue can only have one active consumer. This allows Cloudflare Queues to achieve at least once delivery and minimize the risk of duplicate messages beyond that.
:::note[Best practice]
diff --git a/src/content/docs/queues/tutorials/handle-rate-limits/index.mdx b/src/content/docs/queues/tutorials/handle-rate-limits/index.mdx
index d7b82384ac54f16..ab05871bfbe181f 100644
--- a/src/content/docs/queues/tutorials/handle-rate-limits/index.mdx
+++ b/src/content/docs/queues/tutorials/handle-rate-limits/index.mdx
@@ -77,6 +77,10 @@ Created queue rate-limit-queue.
In your `wrangler.toml` file, add the following:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[queues.producers]]
binding = "EMAIL_QUEUE"
@@ -89,10 +93,16 @@ max_batch_timeout = 10
max_retries = 3
```
+
+
It is important to include the `max_batch_size` of two to the consumer queue is important because the Resend API has a default rate limit of two requests per second. This batch size allows the queue to process the message in the batch size of two. If the batch size is less than two, the queue will wait for 10 seconds to collect the next message. If no more messages are available, the queue will process the message in the batch. For more information, refer to the [Batching, Retries and Delays documentation](/queues/configuration/batching-retries)
Your final `wrangler.toml` file should look similar to the example below.
+
+
+
+
```toml title="wrangler.toml"
#:schema node_modules/wrangler/config-schema.json
name = "resend-rate-limit-queue"
@@ -111,6 +121,8 @@ max_batch_timeout = 10
max_retries = 3
```
+
+
## 3. Add bindings to environment
Add the bindings to the environment interface in `worker-configuration.d.ts`, so TypeScript correctly types the bindings. Type the queue as `Queue`. Refer to the following step for instructions on how to change this type.
diff --git a/src/content/docs/queues/tutorials/web-crawler-with-browser-rendering/index.mdx b/src/content/docs/queues/tutorials/web-crawler-with-browser-rendering/index.mdx
index ff350ddfc6ed2dc..e364e5a2bbaaee9 100644
--- a/src/content/docs/queues/tutorials/web-crawler-with-browser-rendering/index.mdx
+++ b/src/content/docs/queues/tutorials/web-crawler-with-browser-rendering/index.mdx
@@ -86,6 +86,10 @@ id = ""
Then, in your `wrangler.toml` file, add the following with the values generated in the terminal:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
kv_namespaces = [
{ binding = "CRAWLER_SCREENSHOTS_KV", id = "" },
@@ -93,6 +97,8 @@ kv_namespaces = [
]
```
+
+
## 3. Set up Browser Rendering
Now, you need to set up your Worker for Browser Rendering.
@@ -106,10 +112,16 @@ npm install robots-parser
Then, add a Browser Rendering binding. Adding a Browser Rendering binding gives the Worker access to a headless Chromium instance you will control with Puppeteer.
+
+
+
+
```toml
browser = { binding = "CRAWLER_BROWSER" }
```
+
+
## 4. Set up a Queue
Now, we need to set up the Queue.
@@ -127,6 +139,10 @@ Created queue queues-web-crawler.
Then, in your `wrangler.toml` file, add the following:
+
+
+
+
```toml
[[queues.consumers]]
queue = "queues-web-crawler"
@@ -137,10 +153,16 @@ queue = "queues-web-crawler"
binding = "CRAWLER_QUEUE"
```
+
+
Adding the `max_batch_timeout` of 60 seconds to the consumer queue is important because Browser Rendering has a limit of two new browsers per minute per account. This timeout waits up to a minute before collecting queue messages into a batch. The Worker will then remain under this browser invocation limit.
Your final `wrangler.toml` file should look similar to the one below.
+
+
+
+
```toml
#:schema node_modules/wrangler/config-schema.json
name = "web-crawler"
@@ -164,6 +186,8 @@ queue = "queues-web-crawler"
binding = "CRAWLER_QUEUE"
```
+
+
## 5. Add bindings to environment
Add the bindings to the environment interface in `src/index.ts`, so TypeScript correctly types the bindings. Type the queue as `Queue`. The following step will show you how to change this type.
diff --git a/src/content/docs/r2/api/workers/workers-api-reference.mdx b/src/content/docs/r2/api/workers/workers-api-reference.mdx
index bce54fcc9041bd3..9a18d7760506eb0 100644
--- a/src/content/docs/r2/api/workers/workers-api-reference.mdx
+++ b/src/content/docs/r2/api/workers/workers-api-reference.mdx
@@ -27,12 +27,18 @@ A binding is defined in the `wrangler.toml` file of your Worker project's direct
To bind your R2 bucket to your Worker, add the following to your `wrangler.toml` file. Update the `binding` property to a valid JavaScript variable identifier and `bucket_name` to the name of your R2 bucket:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[r2_buckets]]
binding = 'MY_BUCKET' # <~ valid JavaScript variable name
bucket_name = ''
```
+
+
Within your Worker, your bucket binding is now available under the `MY_BUCKET` variable and you can begin interacting with it using the [bucket methods](#bucket-method-definitions) described below.
## Bucket method definitions
@@ -87,9 +93,9 @@ export default {
* `list`
* Returns an R2Objects containing a list of R2Object contained within the bucket.
- * The returned list of objects is ordered lexicographically.
+ * The returned list of objects is ordered lexicographically.
* Returns up to 1000 entries, but may return less in order to minimize memory pressure within the Worker.
- * To explicitly set the number of objects to list, provide an [R2ListOptions](/r2/api/workers/workers-api-reference/#r2listoptions) object with the `limit` property set.
+ * To explicitly set the number of objects to list, provide an [R2ListOptions](/r2/api/workers/workers-api-reference/#r2listoptions) object with the `limit` property set.
* `createMultipartUpload`
@@ -125,7 +131,7 @@ export default {
:::note
-Cloudflare recommends using the `httpEtag` field when returning an etag in a response header. This ensures the etag is quoted and conforms to [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#section-8.8.3).
+Cloudflare recommends using the `httpEtag` field when returning an etag in a response header. This ensures the etag is quoted and conforms to [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#section-8.8.3).
:::
* The etag associated with the object upload.
diff --git a/src/content/docs/r2/api/workers/workers-api-usage.mdx b/src/content/docs/r2/api/workers/workers-api-usage.mdx
index c0397e320b600e9..7ca5d9c8d1102c2 100644
--- a/src/content/docs/r2/api/workers/workers-api-usage.mdx
+++ b/src/content/docs/r2/api/workers/workers-api-usage.mdx
@@ -64,12 +64,18 @@ A binding is defined in the `wrangler.toml` file of your Worker project's direct
To bind your R2 bucket to your Worker, add the following to your `wrangler.toml` file. Update the `binding` property to a valid JavaScript variable identifier and `bucket_name` to the `` you used to create your bucket in [step 2](#2-create-your-bucket):
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[r2_buckets]]
binding = 'MY_BUCKET' # <~ valid JavaScript variable name
bucket_name = ''
```
+
+
Find more detailed information on configuring your Worker in the [Wrangler Configuration documentation](/workers/wrangler/configuration/).
## 4. Access your R2 bucket from your Worker
diff --git a/src/content/docs/r2/reference/data-location.mdx b/src/content/docs/r2/reference/data-location.mdx
index d48fdec3291a9f1..a22809f173ba16b 100644
--- a/src/content/docs/r2/reference/data-location.mdx
+++ b/src/content/docs/r2/reference/data-location.mdx
@@ -79,6 +79,10 @@ Use Jurisdictional Restrictions when you need to ensure data is stored and proce
To access R2 buckets that belong to a jurisdiction from [Workers](/workers/), you will need to specify the jurisdiction as well as the bucket name as part of your [bindings](/r2/api/workers/workers-api-usage/#3-bind-your-bucket-to-a-worker) in your `wrangler.toml`:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[r2_buckets]]
bindings = [
@@ -86,6 +90,8 @@ bindings = [
]
```
+
+
For more information on getting started, refer to [Use R2 from Workers](/r2/api/workers/workers-api-usage/).
### Using jurisdictions with the S3 API
diff --git a/src/content/docs/r2/tutorials/summarize-pdf.mdx b/src/content/docs/r2/tutorials/summarize-pdf.mdx
index c2e61dc1ac79d1d..f38c064de1cc282 100644
--- a/src/content/docs/r2/tutorials/summarize-pdf.mdx
+++ b/src/content/docs/r2/tutorials/summarize-pdf.mdx
@@ -63,11 +63,17 @@ cd pdf-summarizer
Using Static Assets, you can serve the front-end of your application from your Worker. To use Static Assets, you need to add the required bindings to your `wrangler.toml` file.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[assets]
directory = "public"
```
+
+
Next, create a `public` directory and add an `index.html` file. The `index.html` file should contain the following HTML code:
@@ -233,12 +239,18 @@ When you open the URL in your browser, you will see that there is a file upload
To handle the file upload, you will first need to add the R2 binding. In the `wrangler.toml` file, add the following code:
+
+
+
+
```toml
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = ""
```
+
+
Replace `` with the name of your R2 bucket.
Next, update the `src/index.ts` file. The `src/index.ts` file should contain the following code:
@@ -297,11 +309,17 @@ npx wrangler queues create pdf-summarizer
Add the binding to the `wrangler.toml` file:
+
+
+
+
```toml title="wrangler.toml"
[[queues.consumers]]
queue = "pdf-summarizer"
```
+
+
## 5. Handle event notifications
Now that you have a queue to receive event notifications, you need to update the Worker to handle the event notifications. You will need to add a Queue handler that will extract the textual content from the PDF, use Workers AI to summarize the content, and then save it in the R2 bucket.
@@ -375,11 +393,17 @@ The above code does the following:
To use Workers AI, you will need to add the Workers AI binding to the `wrangler.toml` file. The `wrangler.toml` file should contain the following code:
+
+
+
+
```toml title="wrangler.toml"
[ai]
binding = "AI"
```
+
+
Execute the following command to add the AI type definition:
```sh
diff --git a/src/content/docs/r2/tutorials/upload-logs-event-notifications.mdx b/src/content/docs/r2/tutorials/upload-logs-event-notifications.mdx
index bee40d95eef5d5e..7bde1ddeae05a30 100644
--- a/src/content/docs/r2/tutorials/upload-logs-event-notifications.mdx
+++ b/src/content/docs/r2/tutorials/upload-logs-event-notifications.mdx
@@ -87,6 +87,10 @@ cd consumer-worker
In your Worker project's [`wrangler.toml`](/workers/wrangler/configuration/) file, add a [queue consumer](/workers/wrangler/configuration/#queues) and [R2 bucket binding](/workers/wrangler/configuration/#r2-buckets). The queues consumer bindings will register your Worker as a consumer of your future event notifications and the R2 bucket bindings will allow your Worker to access your R2 bucket.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "event-notification-writer"
main = "src/index.ts"
@@ -103,6 +107,8 @@ binding = "LOG_SINK"
bucket_name = "example-log-sink-bucket"
```
+
+
## 6. Write event notification messages to R2
Add a [`queue` handler](/queues/configuration/javascript-apis/#consumer) to `src/index.ts` to handle writing batches of notifications to our log sink bucket (you do not need a [fetch handler](/workers/runtime-apis/handlers/fetch/)):
diff --git a/src/content/docs/radar/investigate/bgp-anomalies.mdx b/src/content/docs/radar/investigate/bgp-anomalies.mdx
index b58bfd98ecf3f19..476e9e6c1f990de 100644
--- a/src/content/docs/radar/investigate/bgp-anomalies.mdx
+++ b/src/content/docs/radar/investigate/bgp-anomalies.mdx
@@ -201,6 +201,10 @@ cd hijack-alerts
In your `wrangler.toml` file, change the default checking frequency (once per hour) to what you like. Here is an example
of configuring the workers to run the script five minutes.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "hijack-alerts"
main = "src/index.js"
@@ -210,8 +214,14 @@ compatibility_date = "2023-04-27"
crons = [ "*/5 * * * *" ]
```
+
+
In this example, we will also need to use Cloudflare KV to save the latest checked event IDs which allows us to know what events are new. Once you have created a KV, you can head back to the `wranglers.toml` file and add the following sections:
+
+
+
+
```toml
[[kv_namespaces]]
binding = "HIJACKS_KV"
@@ -219,6 +229,8 @@ id = "KV_ID_FOR_PRODUCTION"
preview_id = "TEMPORARY_KV_FOR_DEV_ENVIRONMENT"
```
+
+
### Fetch for newly detected BGP hijacks
Start with the API fetching function.
@@ -362,12 +374,18 @@ If you have [Email Routing][email-routing] enabled for your domain, you can also
For this alert to work, you will need to configure the proper email bindings in the [`wrangler.toml`][wrangler-send-email] file.
+
+
+
+
```toml
send_email = [
{type = "send_email", name = "SEND_EMAIL_BINDING", destination_address = "@example.com"},
]
```
+
+
Then, you can create an email-sending function to send alert emails to your configured destination address:
```javascript
diff --git a/src/content/docs/vectorize/get-started/embeddings.mdx b/src/content/docs/vectorize/get-started/embeddings.mdx
index c89599c3f7bf214..97206d509642403 100644
--- a/src/content/docs/vectorize/get-started/embeddings.mdx
+++ b/src/content/docs/vectorize/get-started/embeddings.mdx
@@ -111,12 +111,18 @@ You must create a binding for your Worker to connect to your Vectorize index. [B
To bind your index to your Worker, add the following to the end of your `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[vectorize]]
binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
index_name = "embeddings-index"
```
+
+
Specifically:
- The value (string) you set for `` will be used to reference this database in your Worker. In this tutorial, name your binding `VECTORIZE`.
@@ -129,6 +135,10 @@ Before you deploy your embedding example, ensure your Worker uses your model cat
From within the `embeddings-tutorial` directory, open your `wrangler.toml` file in your editor and add the new `[[ai]]` binding to make Workers AI's models available in your Worker:
+
+
+
+
```toml
[[vectorize]]
binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
@@ -138,6 +148,8 @@ index_name = "embeddings-index"
binding = "AI" # available in your Worker on env.AI
```
+
+
With Workers AI ready, you can write code in your Worker.
## 5. Write code in your Worker
diff --git a/src/content/docs/vectorize/get-started/intro.mdx b/src/content/docs/vectorize/get-started/intro.mdx
index e49b7823a7efa5b..9bd0c1402a096e1 100644
--- a/src/content/docs/vectorize/get-started/intro.mdx
+++ b/src/content/docs/vectorize/get-started/intro.mdx
@@ -118,12 +118,18 @@ You must create a binding for your Worker to connect to your Vectorize index. [B
To bind your index to your Worker, add the following to the end of your `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[vectorize]]
binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
index_name = "tutorial-index"
```
+
+
Specifically:
- The value (string) you set for `` will be used to reference this database in your Worker. In this tutorial, name your binding `VECTORIZE`.
diff --git a/src/content/docs/vectorize/reference/client-api.mdx b/src/content/docs/vectorize/reference/client-api.mdx
index d15857b26c8f8f7..1494a79c03e844e 100644
--- a/src/content/docs/vectorize/reference/client-api.mdx
+++ b/src/content/docs/vectorize/reference/client-api.mdx
@@ -204,12 +204,18 @@ Bindings are defined in either the [`wrangler.toml`](/workers/wrangler/configura
Vectorize indexes are bound by name. A binding for an index named `production-doc-search` would resemble the below:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[vectorize]]
binding = "PROD_SEARCH" # the index will be available as env.PROD_SEARCH in your Worker
index_name = "production-doc-search"
```
+
+
Refer to the [bindings documentation](/workers/wrangler/configuration/#vectorize-indexes) for more details.
## TypeScript Types
diff --git a/src/content/docs/workers-ai/configuration/bindings.mdx b/src/content/docs/workers-ai/configuration/bindings.mdx
index 6fe530a57adc75e..bcc052d223d4655 100644
--- a/src/content/docs/workers-ai/configuration/bindings.mdx
+++ b/src/content/docs/workers-ai/configuration/bindings.mdx
@@ -16,11 +16,17 @@ To use Workers AI with Workers, you must create a Workers AI [binding](/workers/
To bind Workers AI to your Worker, add the following to the end of your `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[ai]
binding = "AI" # i.e. available in your Worker on env.AI
```
+
+
## Pages Functions
[Pages Functions](/pages/functions/) allow you to build full-stack applications with Cloudflare Pages by executing code on the Cloudflare network. Functions are Workers under the hood.
diff --git a/src/content/docs/workers-ai/get-started/workers-wrangler.mdx b/src/content/docs/workers-ai/get-started/workers-wrangler.mdx
index 4017a55403c5879..98e3490467ac8d9 100644
--- a/src/content/docs/workers-ai/get-started/workers-wrangler.mdx
+++ b/src/content/docs/workers-ai/get-started/workers-wrangler.mdx
@@ -52,11 +52,17 @@ You must create an AI binding for your Worker to connect to Workers AI. [Binding
To bind Workers AI to your Worker, add the following to the end of your `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
[ai]
binding = "AI"
```
+
+
Your binding is [available in your Worker code](/workers/reference/migrate-to-module-workers/#bindings-in-es-modules-format) on [`env.AI`](/workers/runtime-apis/handlers/fetch/).
{/* */}
diff --git a/src/content/docs/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai.mdx b/src/content/docs/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai.mdx
index 27e42747765c814..4ad2c97cd10a1de 100644
--- a/src/content/docs/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai.mdx
+++ b/src/content/docs/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai.mdx
@@ -92,11 +92,17 @@ To begin using Cloudflare's AI products, you can add the `ai` block to `wrangler
This example features the [`@cf/meta/llama-3-8b-instruct` model](/workers-ai/models/llama-3-8b-instruct/), which generates text.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[ai]
binding = "AI"
```
+
+
Now, find the `src/index.js` file. Inside the `fetch` handler, you can query the `AI` binding:
```js
@@ -141,6 +147,10 @@ npx wrangler vectorize create vector-index --dimensions=768 --metric=cosine
Then, add the configuration details for your new Vectorize index to `wrangler.toml`:
+
+
+
+
```toml
# ... existing wrangler configuration
@@ -149,6 +159,8 @@ binding = "VECTOR_INDEX"
index_name = "vector-index"
```
+
+
A vector index allows you to store a collection of dimensions, which are floating point numbers used to represent your data. When you want to query the vector database, you can also convert your query into dimensions. **Vectorize** is designed to efficiently determine which stored vectors are most similar to your query.
To implement the searching feature, you must set up a D1 database from Cloudflare. In D1, you can store your app's data. Then, you change this data into a vector format. When someone searches and it matches the vector, you can show them the matching data.
@@ -161,6 +173,10 @@ npx wrangler d1 create database
Then, paste the configuration details output from the previous command into `wrangler.toml`:
+
+
+
+
```toml
# ... existing wrangler configuration
@@ -170,6 +186,8 @@ database_name = "database"
database_id = "abc-def-geh" # replace this with a real database_id (UUID)
```
+
+
In this application, we'll create a `notes` table in D1, which will allow us to store notes and later retrieve them in Vectorize. To create this table, run a SQL command using `wrangler d1 execute`:
```sh
diff --git a/src/content/docs/workers-ai/tutorials/using-bigquery-with-workers-ai.mdx b/src/content/docs/workers-ai/tutorials/using-bigquery-with-workers-ai.mdx
index a034696b4b6def3..82e0158215487a2 100644
--- a/src/content/docs/workers-ai/tutorials/using-bigquery-with-workers-ai.mdx
+++ b/src/content/docs/workers-ai/tutorials/using-bigquery-with-workers-ai.mdx
@@ -447,11 +447,17 @@ formattedResults = formattedResults?.map((formattedResult, i) => {
Uncomment the following lines from the `wrangler.toml` file in your project:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[ai]
binding = "AI"
```
+
+
Restart the Worker that is running locally, and after doing so, go to your application endpoint:
```sh
diff --git a/src/content/docs/workers/configuration/compatibility-dates.mdx b/src/content/docs/workers/configuration/compatibility-dates.mdx
index b0df9b0c3f7f834..85928ed9c42382a 100644
--- a/src/content/docs/workers/configuration/compatibility-dates.mdx
+++ b/src/content/docs/workers/configuration/compatibility-dates.mdx
@@ -25,11 +25,17 @@ However, even though you do not need to update the `compatibility_date` field, i
The compatibility date can be set in a Worker's [`wrangler.toml`](/workers/wrangler/configuration/) file.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
# Opt into backwards-incompatible changes through April 5, 2022.
compatibility_date = "2022-04-05"
```
+
+
#### Via the Cloudflare Dashboard
When a Worker is created through the Cloudflare Dashboard, the compatibility date is automatically set to the current date.
diff --git a/src/content/docs/workers/configuration/compatibility-flags.mdx b/src/content/docs/workers/configuration/compatibility-flags.mdx
index f7c529b70a73930..4fe2381c8ed0ba9 100644
--- a/src/content/docs/workers/configuration/compatibility-flags.mdx
+++ b/src/content/docs/workers/configuration/compatibility-flags.mdx
@@ -22,6 +22,10 @@ Compatibility flags can be set in a Worker's [`wrangler.toml`](/workers/wrangler
This example enables the specific flag `formdata_parser_supports_files`, which is described [below](/workers/configuration/compatibility-flags/#formdata-parsing-supports-file). As of the specified date, `2021-09-14`, this particular flag was not yet enabled by default, but, by specifying it in `compatibility_flags`, we can enable it anyway. `compatibility_flags` can also be used to disable changes that became the default in the past.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
# Opt into backwards-incompatible changes through September 14, 2021.
compatibility_date = "2021-09-14"
@@ -29,6 +33,8 @@ compatibility_date = "2021-09-14"
compatibility_flags = [ "formdata_parser_supports_files" ]
```
+
+
#### Via the Cloudflare Dashboard
Compatibility flags can be updated in the Workers settings on the [Cloudflare dashboard](https://dash.cloudflare.com/).
@@ -49,18 +55,30 @@ compatibility_date to 2024-09-23 or later.
A [growing subset](/workers/runtime-apis/nodejs/) of Node.js APIs are available directly as [Runtime APIs](/workers/runtime-apis/nodejs), with no need to add polyfills to your own code. To enable these APIs in your Worker, add the `nodejs_compat` compatibility flag to your `wrangler.toml`:
+
+
+
+
```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_compat" ]
```
+
+
As additional Node.js APIs are added, they will be made available under the `nodejs_compat` compatibility flag. Unlike most other compatibility flags, we do not expect the `nodejs_compat` to become active by default at a future date.
The Node.js `AsyncLocalStorage` API is a particularly useful feature for Workers. To enable only the `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag.
+
+
+
+
```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_als" ]
```
+
+
## Flags history
Newest flags are listed first.
diff --git a/src/content/docs/workers/configuration/cron-triggers.mdx b/src/content/docs/workers/configuration/cron-triggers.mdx
index 8fd35c98942abec..76d2c88f8e95270 100644
--- a/src/content/docs/workers/configuration/cron-triggers.mdx
+++ b/src/content/docs/workers/configuration/cron-triggers.mdx
@@ -40,6 +40,10 @@ If a Worker is managed with Wrangler, Cron Triggers should be exclusively manage
Refer to the example below for a sample `wrangler.toml` Cron Triggers configuration:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[triggers]
# Schedule cron triggers:
@@ -49,13 +53,21 @@ Refer to the example below for a sample `wrangler.toml` Cron Triggers configurat
crons = [ "*/3 * * * *", "0 15 1 * *", "59 23 LW * *" ]
```
+
+
You also can set a different Cron Trigger for each [environment](/workers/wrangler/environments/) in your `wrangler.toml`. You need to put the `[triggers]` table under your chosen environment. For example:
+
+
+
+
```toml
[env.dev.triggers]
crons = ["0 * * * *"]
```
+
+
#### Via the dashboard
To add Cron Triggers in the Cloudflare dashboard:
diff --git a/src/content/docs/workers/configuration/environment-variables.mdx b/src/content/docs/workers/configuration/environment-variables.mdx
index 4bec6af6a03acba..d64e189fd25748f 100644
--- a/src/content/docs/workers/configuration/environment-variables.mdx
+++ b/src/content/docs/workers/configuration/environment-variables.mdx
@@ -52,6 +52,10 @@ export default {
To define environment variables for different environments, refer to the example below:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "my-worker-dev"
@@ -66,6 +70,8 @@ API_ACCOUNT_ID = "production_example_user"
SERVICE_X_DATA = { URL = "service-x-api.prod.example", MY_ID = 456 }
```
+
+
For local development with `wrangler dev`, variables in `wrangler.toml` are automatically overridden by any values defined in a `.dev.vars` file located in the root directory of your worker. This is useful for providing values you do not want to check in to source control.
```shell
diff --git a/src/content/docs/workers/configuration/routing/custom-domains.mdx b/src/content/docs/workers/configuration/routing/custom-domains.mdx
index 089ffc1f7d528f2..3dc535f98dfe721 100644
--- a/src/content/docs/workers/configuration/routing/custom-domains.mdx
+++ b/src/content/docs/workers/configuration/routing/custom-domains.mdx
@@ -51,14 +51,24 @@ After you have added the domain or subdomain, Cloudflare will create a new DNS r
To configure a Custom Domain in your `wrangler.toml`, add the `custom_domain=true` option on each pattern under `routes`. For example, to configure a Custom Domain:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
routes = [
{ pattern = "shop.example.com", custom_domain = true }
]
```
+
+
To configure multiple Custom Domains:
+
+
+
+
```toml
routes = [
{ pattern = "shop.example.com", custom_domain = true },
@@ -66,6 +76,8 @@ routes = [
]
```
+
+
## Worker to Worker communication
On the same zone, the only way for a Worker to communicate with another Worker running on a [route](/workers/configuration/routing/routes/#set-up-a-route), or on a [`workers.dev`](/workers/configuration/routing/routes/#routes-with-workersdev) subdomain, is via [service bindings](/workers/runtime-apis/bindings/service-bindings/).
@@ -150,10 +162,16 @@ To migrate the route `example.com/*` in your `wrangler.toml`:
2. Go to **DNS** and delete the CNAME record for `example.com`.
3. Add the following to your `wrangler.toml` file:
+
+
+
+
```toml
routes = [
{ pattern = "example.com", custom_domain = true }
]
```
+
+
4. Run `npx wrangler deploy` to create the Custom Domain your Worker will run on.
diff --git a/src/content/docs/workers/configuration/routing/routes.mdx b/src/content/docs/workers/configuration/routing/routes.mdx
index f07c921b610ef0d..412a92a0ec11f0a 100644
--- a/src/content/docs/workers/configuration/routing/routes.mdx
+++ b/src/content/docs/workers/configuration/routing/routes.mdx
@@ -53,18 +53,28 @@ Before you set up a route, make sure you have a DNS record set up for the [domai
To configure a route using your `wrangler.toml` file, refer to the following example.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
routes = [
- { pattern = "subdomain.example.com/*", zone_name = "example.com" }
+ { pattern = "subdomain.example.com/*", zone_name = "example.com" },
# or
{ pattern = "subdomain.example.com/*", zone_id = "" }
]
```
+
+
Add the `zone_name` or `zone_id` option after each route. The `zone_name` and `zone_id` options are interchangeable. If using `zone_id`, find your zone ID by logging in to the [Cloudflare dashboard](https://dash.cloudflare.com) > select your account > select your website > find the **Zone ID** in the lefthand side of **Overview**.
To add multiple routes:
+
+
+
+
```toml
routes = [
{ pattern = "subdomain.example.com/*", zone_name = "example.com" },
@@ -72,6 +82,8 @@ routes = [
]
```
+
+
:::note
The `zone_id` and `zone_name` options are interchangeable. However, if using Cloudflare for SaaS with a `*/*` pattern, use the `zone_name` option to avoid errors. Currently, [publishing `*/*` routes with a `zone_id` option fails with an `Invalid URL` error](https://github.com/cloudflare/workers-sdk/issues/2953).
diff --git a/src/content/docs/workers/configuration/routing/workers-dev.mdx b/src/content/docs/workers/configuration/routing/workers-dev.mdx
index 7368a06bcf62a49..47fbd2668e4aed4 100644
--- a/src/content/docs/workers/configuration/routing/workers-dev.mdx
+++ b/src/content/docs/workers/configuration/routing/workers-dev.mdx
@@ -23,10 +23,16 @@ Review your `workers.dev` route in your Worker > **Settings** > **Domains & Rout
To disable the `workers.dev` route for a Worker, include the following in your Worker's `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
workers_dev = false
```
+
+
When you redeploy your Worker with this change, the `workers.dev` route will be disabled. Disabling your `workers.dev` subdomain will also make [preview URLs](/workers/configuration/previews) inaccessible.
If you do not specify `workers_dev = false` but add a [`routes` component](/workers/wrangler/configuration/#routes) to your `wrangler.toml`, the value of `workers_dev` will be inferred as `false` on the next deploy.
diff --git a/src/content/docs/workers/configuration/sites/configuration.mdx b/src/content/docs/workers/configuration/sites/configuration.mdx
index 97a7759519c27b8..a0e70ed61fd4cd4 100644
--- a/src/content/docs/workers/configuration/sites/configuration.mdx
+++ b/src/content/docs/workers/configuration/sites/configuration.mdx
@@ -43,6 +43,10 @@ If your project uses [environments](/workers/wrangler/environments/), make sure
Example of a `wrangler.toml`:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "docs-site-blah"
@@ -58,6 +62,8 @@ name = "docs-site-staging"
route = "https://staging.example.com/docs*"
```
+
+
## Storage limits
For very exceptionally large pages, Workers Sites might not work for you. There is a 25 MiB limit per page or file.
@@ -76,24 +82,36 @@ This means that you should use gitignore semantics when declaring which director
If you want to include only a certain set of files or directories in your `bucket`, you can add an `include` field to your `[site]` section of your `wrangler.toml` file:
+
+
+
+
```toml
[site]
bucket = "./public"
include = ["included_dir"] # must be an array.
```
+
+
Wrangler will only upload files or directories matching the patterns in the `include` array.
### Excluding files/directories
If you want to exclude files or directories in your `bucket`, you can add an `exclude` field to your `[site]` section of your `wrangler.toml` file:
+
+
+
+
```toml
[site]
bucket = "./public"
exclude = ["excluded_dir"] # must be an array.
```
+
+
Wrangler will ignore files or directories matching the patterns in the `exclude` array when uploading assets to Workers KV.
### Include > exclude
diff --git a/src/content/docs/workers/configuration/sites/start-from-existing.mdx b/src/content/docs/workers/configuration/sites/start-from-existing.mdx
index 358b21ee07f0f78..6c00ad676f8aa8a 100644
--- a/src/content/docs/workers/configuration/sites/start-from-existing.mdx
+++ b/src/content/docs/workers/configuration/sites/start-from-existing.mdx
@@ -5,7 +5,7 @@ sidebar:
order: 1
---
-import { Render, TabItem, Tabs } from "~/components";
+import { Render, TabItem, Tabs, WranglerConfig } from "~/components";
@@ -36,11 +36,15 @@ To deploy a pre-existing static site project, start with a pre-generated site. W
2. Add your site’s build/output directory to the `wrangler.toml` file:
+
+
```toml
[site]
bucket = "./public" # <-- Add your build directory name here.
```
+
+
The default directories for the most popular static site generators are listed below:
- Hugo: `public`
@@ -122,10 +126,16 @@ async function handleEvent(event) {
6. Deploy your site to a [custom domain](/workers/configuration/routing/custom-domains/) that you own and have already attached as a Cloudflare zone. Add a `route` property to the `wrangler.toml` file.
+
+
+
+
```toml
route = "https://example.com/*"
```
+
+
:::note
Refer to the documentation on [Routes](/workers/configuration/routing/routes/) to configure a `route` properly.
diff --git a/src/content/docs/workers/configuration/sites/start-from-scratch.mdx b/src/content/docs/workers/configuration/sites/start-from-scratch.mdx
index 8dc8cbaada82b8a..f7312ead5b407df 100644
--- a/src/content/docs/workers/configuration/sites/start-from-scratch.mdx
+++ b/src/content/docs/workers/configuration/sites/start-from-scratch.mdx
@@ -5,7 +5,7 @@ sidebar:
order: 2
---
-import { Render } from "~/components";
+import { Render, WranglerConfig } from "~/components";
@@ -50,22 +50,38 @@ The template project contains the following files and directories:
- Change the `name` property to the name of your project:
+
+
```toml
name = "my-site"
```
+
+
- Consider updating`compatibility_date` to today's date to get access to the most recent Workers features:
+
+
+
+
```toml
compatibility_date = "yyyy-mm-dd"
```
+
+
- Deploy your site to a [custom domain](/workers/configuration/routing/custom-domains/) that you own and have already attached as a Cloudflare zone:
+
+
+
+
```toml
route = "https://example.com/*"
```
+
+
:::note
Refer to the documentation on [Routes](/workers/configuration/routing/routes/) to configure a `route` properly.
diff --git a/src/content/docs/workers/configuration/sites/start-from-worker.mdx b/src/content/docs/workers/configuration/sites/start-from-worker.mdx
index cefc8aff93de62d..403b6dddbb553a3 100644
--- a/src/content/docs/workers/configuration/sites/start-from-worker.mdx
+++ b/src/content/docs/workers/configuration/sites/start-from-worker.mdx
@@ -5,7 +5,7 @@ sidebar:
order: 3
---
-import { Render, TabItem, Tabs } from "~/components";
+import { Render, TabItem, Tabs, WranglerConfig } from "~/components";
@@ -19,11 +19,15 @@ If you have a pre-existing Worker project, you can use Workers Sites to serve st
2. Add configuration to your `wrangler.toml` file to point to it.
+
+
```toml
[site]
bucket = "./public" # Add the directory with your static assets!
```
+
+
3. Install the `@cloudflare/kv-asset-handler` package in your project:
```sh
diff --git a/src/content/docs/workers/configuration/smart-placement.mdx b/src/content/docs/workers/configuration/smart-placement.mdx
index c289a21bcb3029a..1092eb47c2e2928 100644
--- a/src/content/docs/workers/configuration/smart-placement.mdx
+++ b/src/content/docs/workers/configuration/smart-placement.mdx
@@ -9,6 +9,8 @@ sidebar:
text: Beta
---
+import { WranglerConfig } from "~/components";
+
By default, [Workers](/workers/) and [Pages Functions](/pages/functions/) are invoked in a data center closest to where the request was received. If you are running back-end logic in a Worker, it may be more performant to run that Worker closer to your back-end infrastructure rather than the end user. Smart Placement automatically places your workloads in an optimal location that minimizes latency and speeds up your applications.
## Background
@@ -45,11 +47,15 @@ To enable Smart Placement via Wrangler:
2. Add the following to your Worker project's `wrangler.toml` file:
+
+
```toml
[placement]
mode = "smart"
```
+
+
3. Wait for Smart Placement to analyze your Worker. This process may take up to 15 minutes.
4. View your Worker's [request duration analytics](/workers/observability/metrics-and-analytics/#request-duration).
diff --git a/src/content/docs/workers/examples/cron-trigger.mdx b/src/content/docs/workers/examples/cron-trigger.mdx
index e5101c96099ab47..1260b238dd734b7 100644
--- a/src/content/docs/workers/examples/cron-trigger.mdx
+++ b/src/content/docs/workers/examples/cron-trigger.mdx
@@ -48,6 +48,10 @@ Refer to [Cron Triggers](/workers/configuration/cron-triggers/) for more informa
If you are deploying with Wrangler, set the cron syntax (once per hour as shown below) by adding this to your `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "worker"
@@ -57,13 +61,21 @@ name = "worker"
crons = ["0 * * * *"]
```
+
+
You also can set a different Cron Trigger for each [environment](/workers/wrangler/environments/) in your `wrangler.toml`. You need to put the `[triggers]` table under your chosen environment. For example:
+
+
+
+
```toml
[env.dev.triggers]
crons = ["0 * * * *"]
```
+
+
## Test Cron Triggers using Wrangler
The recommended way of testing Cron Triggers is using Wrangler.
diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx
index 327076f37162a30..411f6d83cc6c9db 100644
--- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx
+++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx
@@ -61,6 +61,10 @@ npm install --save-dev @opennextjs/cloudflare
Then, add a [`wrangler.toml`](/workers/wrangler/configuration/) file to the root directory of your Next.js app:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
main = ".worker-next/index.mjs"
name = "my-app"
@@ -69,6 +73,8 @@ compatibility_flags = ["nodejs_compat"]
experimental_assets = { directory = ".worker-next/assets", binding = "ASSETS" }
```
+
+
:::note
As shown above, you must enable the [`nodejs_compat` compatibility flag](/workers/runtime-apis/nodejs/) _and_ set your [compatibility date](/workers/configuration/compatibility-dates/) to `2024-09-23` or later for your Next.js app to work with @opennextjs/cloudflare.
:::
@@ -105,12 +111,18 @@ npx wrangler@latest kv namespace create NEXT_CACHE_WORKERS_KV
#### Add the KV namespace to your Worker
+
+
+
+
```toml
[[kv_namespaces]]
binding = "NEXT_CACHE_WORKERS_KV"
id = ""
```
+
+
#### Set the name of the binding to `NEXT_CACHE_WORKERS_KV`
As shown above, the name of the binding that you configure for the KV namespace must be set to `NEXT_CACHE_WORKERS_KV`.
diff --git a/src/content/docs/workers/languages/python/ffi.mdx b/src/content/docs/workers/languages/python/ffi.mdx
index 7b4ef05772b722d..fc0683958a47a12 100644
--- a/src/content/docs/workers/languages/python/ffi.mdx
+++ b/src/content/docs/workers/languages/python/ffi.mdx
@@ -22,6 +22,10 @@ Bindings allow your Worker to interact with resources on the Cloudflare Develope
For example, to access a [KV](/kv) namespace from a Python Worker, you would declare the following in your Worker's [`wrangler.toml`](/workers/wrangler/configuration/):
+import { WranglerConfig } from "~/components";
+
+
+
```toml
main = "./src/index.py"
kv_namespaces = [
@@ -29,6 +33,8 @@ kv_namespaces = [
]
```
+
+
...and then call `.get()` on the binding object that is exposed on `env`:
```python
diff --git a/src/content/docs/workers/languages/python/how-python-workers-work.mdx b/src/content/docs/workers/languages/python/how-python-workers-work.mdx
index 1578fc60d2586fc..0a895058ab5c34c 100644
--- a/src/content/docs/workers/languages/python/how-python-workers-work.mdx
+++ b/src/content/docs/workers/languages/python/how-python-workers-work.mdx
@@ -26,12 +26,18 @@ async def on_fetch(request, env):
…with a wrangler.toml file that points to a .py file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "hello-world-python-worker"
main = "src/entry.py"
compatibility_date = "2024-04-01"
```
+
+
When you run `npx wrangler@latest dev` in local dev, the Workers runtime will:
1. Determine which version of Pyodide is required, based on your compatibility date
diff --git a/src/content/docs/workers/languages/python/index.mdx b/src/content/docs/workers/languages/python/index.mdx
index 0a428ebeb13f7f5..8f062f87a4f7b3f 100644
--- a/src/content/docs/workers/languages/python/index.mdx
+++ b/src/content/docs/workers/languages/python/index.mdx
@@ -124,6 +124,10 @@ the Python `fetch` handler and can be used to access
For example, let's try setting and using an environment variable in a Python
Worker. First, add the environment variable to your Worker's `wrangler.toml`:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "hello-python-worker"
main = "src/entry.py"
@@ -134,6 +138,8 @@ compatibility_date = "2024-03-20"
API_HOST = "example.com"
```
+
+
Then, you can access the `API_HOST` environment variable via the `env` parameter:
```python
diff --git a/src/content/docs/workers/languages/rust/index.mdx b/src/content/docs/workers/languages/rust/index.mdx
index 0d6160ac3ab0a60..db3b20220873191 100644
--- a/src/content/docs/workers/languages/rust/index.mdx
+++ b/src/content/docs/workers/languages/rust/index.mdx
@@ -212,6 +212,10 @@ To run the resulting Wasm binary on Workers, `workers-rs` includes a build tool
Unoptimized Rust Wasm binaries can be large and may exceed Worker bundle size limits or experience long startup times. The template project pre-configures several useful size optimizations in your `Cargo.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[profile.release]
lto = true
@@ -219,6 +223,8 @@ strip = true
codegen-units = 1
```
+
+
Finally, `worker-bundle` automatically invokes [`wasm-opt`](https://github.com/brson/wasm-opt-rs) to further optimize binary size before upload.
## Related resources
diff --git a/src/content/docs/workers/observability/logs/logpush.mdx b/src/content/docs/workers/observability/logs/logpush.mdx
index cdb232e83250cb9..1472b5baa1f50c9 100644
--- a/src/content/docs/workers/observability/logs/logpush.mdx
+++ b/src/content/docs/workers/observability/logs/logpush.mdx
@@ -75,6 +75,10 @@ In Logpush, you can configure [filters](/logs/reference/filters/) and a [samplin
Enable logging on your Worker by adding a new property, `logpush = true`, to your `wrangler.toml` file. This can be added either in the top-level configuration or under an [environment](/workers/wrangler/environments/). Any new Workers with this property will automatically get picked up by the Logpush job.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
# Top-level configuration
@@ -87,6 +91,8 @@ logpush = true
route = { pattern = "example.org/*", zone_name = "example.org" }
```
+
+
Configure via multipart script upload API:
```bash
diff --git a/src/content/docs/workers/observability/logs/tail-workers.mdx b/src/content/docs/workers/observability/logs/tail-workers.mdx
index 70a20fa15d5ab9a..dd44434b4af2fd0 100644
--- a/src/content/docs/workers/observability/logs/tail-workers.mdx
+++ b/src/content/docs/workers/observability/logs/tail-workers.mdx
@@ -85,10 +85,16 @@ The following Worker code is an example of what the `events` object may look lik
3. Add the following to the `wrangler.toml` file of the producer Worker:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
tail_consumers = [{service = ""}]
```
+
+
:::note
The Worker that you add a `tail_consumers` binding to must have a `tail()` handler defined.
diff --git a/src/content/docs/workers/observability/logs/workers-logs.mdx b/src/content/docs/workers/observability/logs/workers-logs.mdx
index 70c11aa5e75d4db..80c5558f5961b6a 100644
--- a/src/content/docs/workers/observability/logs/workers-logs.mdx
+++ b/src/content/docs/workers/observability/logs/workers-logs.mdx
@@ -11,7 +11,7 @@ sidebar:
---
-import { TabItem, Tabs, Steps, Render } from "~/components"
+import { TabItem, Tabs, Steps, Render, WranglerConfig } from "~/components"
Workers Logs lets you automatically collect, store, filter, and analyze logging data emitted from Cloudflare Workers. Data is written to your Cloudflare Account, and you can query it in the dashboard for each of your Workers. All newly created Workers will come with the observability setting enabled by default.
@@ -29,24 +29,35 @@ Minimum required Wrangler version: 3.78.6. Check your version by running `wrangl
You must add the observability setting for your Worker to write logs to Workers Logs. Add the following setting to your Worker's `wrangler.toml` file and redeploy your Worker.
+
+
```toml
[observability]
enabled = true
head_sampling_rate = 1 # optional. default = 1.
```
+
+
[Head-based sampling](/workers/observability/logs/workers-logs/#head-based-sampling) allows you set the percentage of Workers requests that are logged.
### Enabling with environments
-[Environments](/workers/wrangler/environments/) allow you to deploy the same Worker application with different configurations. For example, you may want to configure a different `head_sampling_rate` to staging and production. To configure observability for your environment:
- 1. Add the following configuration below `[env.]`
+[Environments](/workers/wrangler/environments/) allow you to deploy the same Worker application with different configurations. For example, you may want to configure a different `head_sampling_rate` to staging and production. To configure observability for an environment named `staging`:
+ 1. Add the following configuration below `[env.staging]`
+
+
+
+
```toml
- [env..observability]
+ [env.staging.observability]
enabled = true
head_sampling_rate = 1 # optional
```
- 2. Deploy your Worker with `npx wrangler deploy -e `
+
+
+
+ 2. Deploy your Worker with `npx wrangler deploy -e staging`
3. Repeat step 1 and 2 for each environment.
## View logs from the dashboard
@@ -84,11 +95,17 @@ In the Workers Logs UI, logs are presented with a localized timestamp and a mess
Invocation logs can be disabled in wrangler by adding the `invocation_logs = false` configuration.
+
+
+
+
```toml
[observability.logs]
invocation_logs = false
```
+
+
| Invocation Handler | Invocation Message |
| --------------------------------------------------------------- | -------------------------- |
| [Alarm](/durable-objects/api/alarms/) | \ |
@@ -156,12 +173,18 @@ Head-based sampling allows you to log a percentage of incoming requests to your
To enable head-based sampling, set `head_sampling_rate` within the observability configuration. The valid range is from 0 to 1, where 0 indicates zero out of one hundred requests are logged, and 1 indicates every request is logged. If `head_sampling_rate` is unspecified, it is configured to a default value of 1 (100%). In the example below, `head_sampling_rate` is set to 0.01, which means one out of every one hundred requests is logged.
+
+
+
+
```toml
[observability]
enabled = true
head_sampling_rate = 0.01 # 1% sampling rate
```
+
+
## Limits
| Description | Retention |
diff --git a/src/content/docs/workers/observability/source-maps.mdx b/src/content/docs/workers/observability/source-maps.mdx
index 287f48d58612ab2..28f4c96d86da2b2 100644
--- a/src/content/docs/workers/observability/source-maps.mdx
+++ b/src/content/docs/workers/observability/source-maps.mdx
@@ -25,10 +25,16 @@ Support for uploading source maps is available now in open beta. Minimum require
To enable source maps, add the following to your Worker's [`wrangler.toml`](/workers/wrangler/configuration/) file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
upload_source_maps = true
```
+
+
When `upload_source_maps` is set to `true`, Wrangler will automatically generate and upload source map files when you run [`wrangler deploy`](/workers/wrangler/commands/#deploy) or [`wrangler versions deploy`](/workers/wrangler/commands/#deploy-2).
diff --git a/src/content/docs/workers/reference/migrate-to-module-workers.mdx b/src/content/docs/workers/reference/migrate-to-module-workers.mdx
index 80b67b008ee68a7..ab7f176c368c2e5 100644
--- a/src/content/docs/workers/reference/migrate-to-module-workers.mdx
+++ b/src/content/docs/workers/reference/migrate-to-module-workers.mdx
@@ -65,12 +65,18 @@ To understand bindings, refer the following `TODO` KV namespace binding example.
2. Create a Worker.
3. Find your Worker's `wrangler.toml` configuration file and add a KV namespace binding:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
kv_namespaces = [
{ binding = "TODO", id = "" }
]
```
+
+
In the following sections, you will use your binding in Service Worker and ES modules format.
:::note[Reference KV from Durable Objects and Workers]
@@ -137,6 +143,10 @@ export { getTodos }
Review the following example environment variable configuration in `wrangler.toml`:
+
+
+
+
```toml
name = "my-worker-dev"
@@ -147,6 +157,8 @@ name = "my-worker-dev"
API_ACCOUNT_ID = ""
```
+
+
### Environment variables in Service Worker format
In Service Worker format, the `API_ACCOUNT_ID` is defined in the global scope of your Worker application. Your `API_ACCOUNT_ID` environment variable is available to use anywhere in your Worker application's code.
diff --git a/src/content/docs/workers/runtime-apis/bindings/index.mdx b/src/content/docs/workers/runtime-apis/bindings/index.mdx
index 09351a255b1a61e..2dba2a391786a51 100644
--- a/src/content/docs/workers/runtime-apis/bindings/index.mdx
+++ b/src/content/docs/workers/runtime-apis/bindings/index.mdx
@@ -18,6 +18,10 @@ The following bindings available today:
When you declare a binding on your Worker, you grant it a specific capability, such as being able to read and write files to an [R2](/r2/) bucket. For example:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
main = "./src/index.js"
r2_buckets = [
@@ -25,6 +29,8 @@ r2_buckets = [
]
```
+
+
```js
export default {
async fetch(request, env) {
diff --git a/src/content/docs/workers/runtime-apis/bindings/mTLS.mdx b/src/content/docs/workers/runtime-apis/bindings/mTLS.mdx
index f846a0b2a4b1666..1677d1ce146bba5 100644
--- a/src/content/docs/workers/runtime-apis/bindings/mTLS.mdx
+++ b/src/content/docs/workers/runtime-apis/bindings/mTLS.mdx
@@ -33,12 +33,18 @@ npx wrangler mtls-certificate upload --cert cert.pem --key key.pem --name my-cli
Then, update your Worker project's `wrangler.toml` file to create an mTLS certificate binding:
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
mtls_certificates = [
{ binding = "MY_CERT", certificate_id = "" }
]
```
+
+
:::note
Certificate IDs are displayed after uploading, and can also be viewed with the command `wrangler mtls-certificate list`.
diff --git a/src/content/docs/workers/runtime-apis/bindings/rate-limit.mdx b/src/content/docs/workers/runtime-apis/bindings/rate-limit.mdx
index 3c2c0fc24719d0e..9e9cf821e4be462 100644
--- a/src/content/docs/workers/runtime-apis/bindings/rate-limit.mdx
+++ b/src/content/docs/workers/runtime-apis/bindings/rate-limit.mdx
@@ -36,6 +36,10 @@ We want your feedback. Tell us what you'd like to see in the [#workers-discussio
First, add a [binding](/workers/runtime-apis/bindings) to your Worker that gives it access to the Rate Limiting API:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
main = "src/index.js"
@@ -53,6 +57,8 @@ namespace_id = "1001"
simple = { limit = 100, period = 60 }
```
+
+
This binding makes the `MY_RATE_LIMITER` binding available, which provides a `limit()` method:
@@ -104,6 +110,10 @@ You can define and configure multiple rate limiting configurations per Worker, w
For example, here is how you can define two rate limiting configurations for free and paid tier users:
+
+
+
+
```toml
main = "src/index.js"
@@ -122,6 +132,8 @@ namespace_id = "1002"
simple = { limit = 1000, period = 60 }
```
+
+
## Configuration
A rate limiting binding has three settings:
@@ -132,6 +144,10 @@ A rate limiting binding has three settings:
For example, to apply a rate limit of 1500 requests per minute, you would define a rate limiting configuration as follows:
+
+
+
+
```toml
[[unsafe.bindings]]
name = "MY_RATE_LIMITER"
@@ -142,6 +158,8 @@ namespace_id = "1001"
simple = { limit = 1500, period = 60 }
```
+
+
## Best practices
The `key` passed to the `limit` function, that determines what to rate limit on, should represent a unique characteristic of a user or class of user that you wish to rate limit.
diff --git a/src/content/docs/workers/runtime-apis/bindings/service-bindings/http.mdx b/src/content/docs/workers/runtime-apis/bindings/service-bindings/http.mdx
index 5ab837fb0e3df94..62cce30a3526fb0 100644
--- a/src/content/docs/workers/runtime-apis/bindings/service-bindings/http.mdx
+++ b/src/content/docs/workers/runtime-apis/bindings/service-bindings/http.mdx
@@ -12,11 +12,17 @@ Worker A that declares a Service binding to Worker B can forward a [`Request`](/
For example, consider the following Worker that implements a [`fetch()` handler](/workers/runtime-apis/handlers/fetch/):
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "worker_b"
main = "./src/workerB.js"
```
+
+
```js
export default {
async fetch(request, env, ctx) {
@@ -27,6 +33,10 @@ export default {
The following Worker declares a binding to the Worker above:
+
+
+
+
```toml
name = "worker_a"
main = "./src/workerA.js"
@@ -35,6 +45,8 @@ services = [
]
```
+
+
And then can forward a request to it:
```js
diff --git a/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx b/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx
index d74534827ce7a18..70c634855c1342f 100644
--- a/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx
+++ b/src/content/docs/workers/runtime-apis/bindings/service-bindings/index.mdx
@@ -32,12 +32,18 @@ You add a Service binding by modifying the `wrangler.toml` of the caller — th
For example, if you want Worker A to be able to call Worker B — you'd add the following to the `wrangler.toml` for Worker A:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
services = [
{ binding = "", service = "" }
]
```
+
+
* `binding`: The name of the key you want to expose on the `env` object.
* `service`: The name of the target Worker you would like to communicate with. This Worker must be on your Cloudflare account.
@@ -52,11 +58,17 @@ Worker A that declares a Service binding to Worker B can call Worker B in two di
First, create the Worker that you want to communicate with. Let's call this "Worker B". Worker B exposes the public method, `add(a, b)`:
+
+
+
+
```toml
name = "worker_b"
main = "./src/workerB.js"
```
+
+
```js
import { WorkerEntrypoint } from "cloudflare:workers";
@@ -70,6 +82,10 @@ export default class WorkerB extends WorkerEntrypoint {
Next, create the Worker that will call Worker B. Let's call this "Worker A". Worker A declares a binding to Worker B. This is what gives it permission to call public methods on Worker B.
+
+
+
+
```toml
name = "worker_a"
main = "./src/workerA.js"
@@ -78,6 +94,8 @@ services = [
]
```
+
+
```js
export default {
async fetch(request, env) {
diff --git a/src/content/docs/workers/runtime-apis/bindings/service-bindings/rpc.mdx b/src/content/docs/workers/runtime-apis/bindings/service-bindings/rpc.mdx
index ccf7f04753a3a0e..ba34c3c6e086230 100644
--- a/src/content/docs/workers/runtime-apis/bindings/service-bindings/rpc.mdx
+++ b/src/content/docs/workers/runtime-apis/bindings/service-bindings/rpc.mdx
@@ -49,6 +49,10 @@ The [`env`](/workers/runtime-apis/bindings) object is exposed as a class propert
For example, a Worker that declares a binding to the [environment variable](/workers/configuration/environment-variables/) `GREETING`:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "my-worker"
@@ -56,6 +60,8 @@ name = "my-worker"
GREETING = "Hello"
```
+
+
Can access it by calling `this.env.GREETING`:
```js
@@ -103,6 +109,10 @@ You can also export any number of named `WorkerEntrypoint` classes from within a
You can use this to group multiple pieces of compute together. For example, you might create a distinct `WorkerEntrypoint` for each permission role in your application, and use these to provide role-specific RPC methods:
+
+
+
+
```toml
name = "todo-app"
@@ -112,6 +122,8 @@ database_name = "todo-app-db"
database_id = ""
```
+
+
```js
import { WorkerEntrypoint } from "cloudflare:workers";
@@ -156,6 +168,10 @@ export default class extends WorkerEntrypoint {
You can then declare a Service binding directly to `AdminEntrypoint` in another Worker:
+
+
+
+
```toml
name = "admin-app"
@@ -165,6 +181,8 @@ service = "todo-app"
entrypoint = "AdminEntrypoint"
```
+
+
```js
export default {
async fetch(request, env) {
diff --git a/src/content/docs/workers/runtime-apis/bindings/version-metadata.mdx b/src/content/docs/workers/runtime-apis/bindings/version-metadata.mdx
index bf6a56c8c60b0f5..a667aa7ef9fff84 100644
--- a/src/content/docs/workers/runtime-apis/bindings/version-metadata.mdx
+++ b/src/content/docs/workers/runtime-apis/bindings/version-metadata.mdx
@@ -21,11 +21,17 @@ Worker version ID, version tag and timestamp of when the version was created are
To use the version metadata binding, update your Worker's `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
[version_metadata]
binding = "CF_VERSION_METADATA"
```
+
+
### Interface
An example of how to access the version ID and version tag from within a Worker to send events to [Workers Analytics Engine](/analytics/analytics-engine/):
diff --git a/src/content/docs/workers/runtime-apis/nodejs/index.mdx b/src/content/docs/workers/runtime-apis/nodejs/index.mdx
index a814d6495cc6364..4918c7dd8e1191d 100644
--- a/src/content/docs/workers/runtime-apis/nodejs/index.mdx
+++ b/src/content/docs/workers/runtime-apis/nodejs/index.mdx
@@ -20,11 +20,17 @@ You can view which APIs are supported using the [Node.js compatability matrix](h
To enable both built-in runtime APIs and polyfills for your Worker or Pages project, add the [`nodejs_compat`](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) [compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) to your `wrangler.toml`, and set your compatibility date to September 23rd, 2024 or later.
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_compat" ]
compatibility_date = "2024-09-23"
```
+
+
:::note
As of September 23rd, 2024, the `nodejs_compat` compatibility flag enables the exact same behavior as the `nodejs_compat_v2` compatibility flag, as long as your compatibility date is set to September 23rd, 2024 or later.
:::
@@ -62,6 +68,12 @@ If an API you wish to use is missing and you want to suggest that Workers suppor
To enable only the Node.js `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag.
+
+
+
+
```toml
compatibility_flags = [ "nodejs_als" ]
```
+
+
diff --git a/src/content/docs/workers/runtime-apis/rpc/index.mdx b/src/content/docs/workers/runtime-apis/rpc/index.mdx
index 73cceca25d7d44f..31210ba17e45e75 100644
--- a/src/content/docs/workers/runtime-apis/rpc/index.mdx
+++ b/src/content/docs/workers/runtime-apis/rpc/index.mdx
@@ -68,11 +68,17 @@ To use an instance of a class that you define as a parameter or return value of
Consider the following example:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "counter"
main = "./src/counter.js"
```
+
+
```js
import { WorkerEntrypoint, RpcTarget } from "cloudflare:workers";
@@ -104,6 +110,10 @@ export default {
The method `increment` can be called directly by the client, as can the public property `value`:
+
+
+
+
```toml
name = "client-worker"
main = "./src/clientWorker.js"
@@ -112,6 +122,8 @@ services = [
]
```
+
+
```js
export default {
async fetch(request, env) {
diff --git a/src/content/docs/workers/static-assets/binding.mdx b/src/content/docs/workers/static-assets/binding.mdx
index 4d2d802e97ecd21..5b67eee1bba24b6 100644
--- a/src/content/docs/workers/static-assets/binding.mdx
+++ b/src/content/docs/workers/static-assets/binding.mdx
@@ -25,16 +25,26 @@ Only one collection of static assets can be configured in each Worker.
The folder of static assets to be served. For many frameworks, this is the `./public/`, `./dist/`, or `./build/` folder.
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
name = "my-worker"
compatibility_date = "2024-09-19"
assets = { directory = "./public/" }
```
+
+
## `binding`
Configuring the optional [binding](/workers/runtime-apis/bindings) gives you access to the collection of assets from within your Worker script.
+
+
+
+
```toml title="wrangler.toml"
name = "my-worker"
main = "./src/index.js"
@@ -43,6 +53,8 @@ compatibility_date = "2024-09-19"
assets = { directory = "./public/", binding = "ASSETS" }
```
+
+
In the example above, assets would be available through `env.ASSETS`.
### Runtime API Reference
diff --git a/src/content/docs/workers/static-assets/routing.mdx b/src/content/docs/workers/static-assets/routing.mdx
index c56d7900a0af282..f7dd0f1a59f1627 100644
--- a/src/content/docs/workers/static-assets/routing.mdx
+++ b/src/content/docs/workers/static-assets/routing.mdx
@@ -99,10 +99,16 @@ Alternate configuration options are outlined on this page and can be specified i
Example `wrangler.toml` configuration:
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
assets = { directory = "./public", binding = "ASSETS", html_handling = "force-trailing-slash", not_found_handling = "404-page" }
```
+
+
#### `html_handling = "auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none"`
Take the following directory structure:
diff --git a/src/content/docs/workers/tutorials/build-a-jamstack-app/index.mdx b/src/content/docs/workers/tutorials/build-a-jamstack-app/index.mdx
index 5cb3989db1e892e..91ac3c3a9d3d9f0 100644
--- a/src/content/docs/workers/tutorials/build-a-jamstack-app/index.mdx
+++ b/src/content/docs/workers/tutorials/build-a-jamstack-app/index.mdx
@@ -89,12 +89,18 @@ npx wrangler kv:namespace create "TODOS" --preview
The associated namespace can be combined with a `--preview` flag to interact with a preview namespace instead of a production namespace. Namespaces can be added to your application by defining them inside your Wrangler configuration. Copy your newly created namespace ID, and in your `wrangler.toml`, define a `kv_namespaces` key to set up your namespace:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
kv_namespaces = [
{binding = "TODOS", id = "", preview_id = ""}
]
```
+
+
The defined namespace, `TODOS`, will now be available inside of your codebase. With that, it is time to understand the [KV API](/kv/api/). A KV namespace has three primary methods you can use to interface with your cache: `get`, `put`, and `delete`.
Start storing data by defining an initial set of data, which you will put inside of the cache using the `put` method. The following example defines a `defaultData` object instead of an array of todo items. You may want to store metadata and other information inside of this cache object later on. Given that data object, use `JSON.stringify` to add a string into the cache:
diff --git a/src/content/docs/workers/tutorials/connect-to-turso-using-workers/index.mdx b/src/content/docs/workers/tutorials/connect-to-turso-using-workers/index.mdx
index 578813395364402..0a81709ac834bb5 100644
--- a/src/content/docs/workers/tutorials/connect-to-turso-using-workers/index.mdx
+++ b/src/content/docs/workers/tutorials/connect-to-turso-using-workers/index.mdx
@@ -156,11 +156,17 @@ libsql://my-db-.turso.io
Open `wrangler.toml` in your editor and at the bottom of the file, create a new `[vars]` section representing the [environment variables](/workers/configuration/environment-variables/) for your project:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[vars]
LIBSQL_DB_URL = "paste-your-url-here"
```
+
+
Save the changes to `wrangler.toml`.
Next, create a long-lived authentication token for your Worker to use when connecting to your database. Run the following Turso CLI command, and copy the output to your clipboard:
diff --git a/src/content/docs/workers/tutorials/create-finetuned-chatgpt-ai-models-with-r2/index.mdx b/src/content/docs/workers/tutorials/create-finetuned-chatgpt-ai-models-with-r2/index.mdx
index 63c2ccafd444b01..095fa59d1c13e3f 100644
--- a/src/content/docs/workers/tutorials/create-finetuned-chatgpt-ai-models-with-r2/index.mdx
+++ b/src/content/docs/workers/tutorials/create-finetuned-chatgpt-ai-models-with-r2/index.mdx
@@ -93,12 +93,18 @@ A binding is how your Worker interacts with external resources such as the R2 bu
To bind the R2 bucket to your Worker, add the following to your `wrangler.toml` file. Update the binding property to a valid JavaScript variable identifier. Replace `` with the name of the bucket you created in [step 2](#2-upload-a-fine-tune-document-to-r2):
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[r2_buckets]]
binding = 'MY_BUCKET' # <~ valid JavaScript variable name
bucket_name = ''
```
+
+
## 4. Initialize your Worker application
You will use [Hono](https://hono.dev/), a lightweight framework for building Cloudflare Workers applications. Hono provides an interface for defining routes and middleware functions. Inside your project directory, run the following command to install Hono:
diff --git a/src/content/docs/workers/tutorials/deploy-a-realtime-chat-app/index.mdx b/src/content/docs/workers/tutorials/deploy-a-realtime-chat-app/index.mdx
index 074623f21b1dbf4..dc023bb0bf6ccf9 100644
--- a/src/content/docs/workers/tutorials/deploy-a-realtime-chat-app/index.mdx
+++ b/src/content/docs/workers/tutorials/deploy-a-realtime-chat-app/index.mdx
@@ -52,22 +52,34 @@ To deploy your application to a custom domain using Wrangler, open your project'
To configure a route in your `wrangler.toml`, add the following to your environment:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
routes = [
{ pattern = "example.com/about", zone_id = "" }
]
```
+
+
If you have specified your zone ID in the environment of your `wrangler.toml`, you will not need to write it again in object form.
To configure a subdomain in your `wrangler.toml`, add the following to your environment:
+
+
+
+
```toml
routes = [
{ pattern = "subdomain.example.com", custom_domain = true }
]
```
+
+
To test your live application:
1. Open your `edge-chat-demo..workers.dev` subdomain. Your subdomain can be found in the [Cloudflare dashboard](https://dash.cloudflare.com) > **Workers & Pages** > your Worker > **Triggers** > **Routes** > select the `edge-chat-demo..workers.dev` route.
@@ -79,6 +91,10 @@ To test your live application:
To uninstall your chat application, modify your `wrangler.toml` file to remove the `durable_objects` bindings and add a `deleted_classes` migration:
+
+
+
+
```toml
[durable_objects]
bindings = [
@@ -94,6 +110,8 @@ tag = "v2"
deleted_classes = ["ChatRoom", "RateLimiter"]
```
+
+
Then run `npx wrangler deploy`.
To delete your Worker:
diff --git a/src/content/docs/workers/tutorials/generate-youtube-thumbnails-with-workers-and-images/index.mdx b/src/content/docs/workers/tutorials/generate-youtube-thumbnails-with-workers-and-images/index.mdx
index 1493ef1b485b41e..48e62c09777b66c 100644
--- a/src/content/docs/workers/tutorials/generate-youtube-thumbnails-with-workers-and-images/index.mdx
+++ b/src/content/docs/workers/tutorials/generate-youtube-thumbnails-with-workers-and-images/index.mdx
@@ -337,11 +337,17 @@ Adding a query parameter with custom text, you should receive:
To deploy your Worker, open your `wrangler.toml` file and update the `name` key with your project's name. Below is an example with this tutorial's project name:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "worker-to-text"
```
+
+
Then run the `npx wrangler deploy` command to deploy your Worker.
```sh
@@ -494,11 +500,17 @@ Image transformations can only be tested when you deploy your Worker.
To deploy your Worker, open your `wrangler.toml` file and update the `name` key with your project's name. Below is an example with this tutorial's project name:
+
+
+
+
```toml
name = "thumbnail-image"
```
+
+
Deploy your Worker by running:
```sh
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 fa0f520a04bcb60..dfd05c38157816d 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
@@ -155,10 +155,16 @@ npx wrangler secret put GITHUB_SECRET_TOKEN
Add the nodejs_compat flag to your `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
compatibility_flags = ["nodejs_compat"]
```
+
+
---
## Sending a text with Twilio
diff --git a/src/content/docs/workers/tutorials/handle-form-submissions-with-airtable/index.mdx b/src/content/docs/workers/tutorials/handle-form-submissions-with-airtable/index.mdx
index 9417ea7597d24b4..8dfcb0a8a582f4f 100644
--- a/src/content/docs/workers/tutorials/handle-form-submissions-with-airtable/index.mdx
+++ b/src/content/docs/workers/tutorials/handle-form-submissions-with-airtable/index.mdx
@@ -238,6 +238,10 @@ To make an authenticated request to Airtable, you need to provide four constants
Add a `vars` table at the end of your `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml null {7}
name = "workers-airtable-form"
main = "src/index.js"
@@ -248,6 +252,8 @@ AIRTABLE_BASE_ID = "exampleBaseId"
AIRTABLE_TABLE_NAME = "Form Submissions"
```
+
+
With all these fields submitted, it is time to deploy your Workers serverless function and get your form communicating with it. First, publish your Worker:
```sh title="Deploy your Worker"
diff --git a/src/content/docs/workers/tutorials/postgres/index.mdx b/src/content/docs/workers/tutorials/postgres/index.mdx
index 8852b8466979209..d8442e56fd6d9ec 100644
--- a/src/content/docs/workers/tutorials/postgres/index.mdx
+++ b/src/content/docs/workers/tutorials/postgres/index.mdx
@@ -61,10 +61,16 @@ cd postgres-tutorial
When creating your Worker application, [enable Node.js APIs](/workers/runtime-apis/nodejs/#enable-nodejs-with-workers) by including the
"nodejs_compat_v2" compatibility flag to your `wrangler.toml`. This will be needed to use the library to connect to your PostgreSQL database.
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
compatibility_flags = ["nodejs_compat_v2"]
```
+
+
## 2. Add the PostgreSQL connection library
To connect to a PostgreSQL database, you will need the `postgres` library. In your Worker application directory, run the following command to install the library:
@@ -107,14 +113,24 @@ npx wrangler secret put DB_URL
Set your `DB_URL` secret locally in a `.dev.vars` file as documented in [Local Development with Secrets](/workers/configuration/secrets/).
+
+
+
+
```toml
DB_URL=""
```
+
+
### Set explicit parameters
Configure each database parameter as an [environment variable](/workers/configuration/environment-variables/) via the [Cloudflare dashboard](/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard) or in your `wrangler.toml` file. Refer to an example of a`wrangler.toml` file configuration:
+
+
+
+
```toml
[vars]
DB_USERNAME = "postgres"
@@ -124,6 +140,8 @@ DB_PORT = "5432"
DB_NAME = "productsdb"
```
+
+
To set your password as a [secret](/workers/configuration/secrets/) so that it is not stored as plain text, use [`wrangler secret put`](/workers/wrangler/commands/#secret). `DB_PASSWORD` is an example variable name for this secret to be accessed in your Worker:
```sh
@@ -312,6 +330,10 @@ You can also use explicit parameters by following the [wrangler documentation fo
This command outputs the Hyperdrive configuration `id` that will be used for your Hyperdrive [binding](/workers/runtime-apis/bindings/). Set up your binding by specifying the `id` in the `wrangler.toml` file.
+
+
+
+
```toml {7-9}
name = "hyperdrive-example"
main = "src/index.ts"
@@ -324,6 +346,8 @@ binding = "HYPERDRIVE"
id = ""
```
+
+
Create the types for your Hyperdrive binding using the following command:
```bash
diff --git a/src/content/docs/workers/tutorials/store-data-with-fauna/index.mdx b/src/content/docs/workers/tutorials/store-data-with-fauna/index.mdx
index 98f1a4da3166a1c..fbbd5c8baf72547 100644
--- a/src/content/docs/workers/tutorials/store-data-with-fauna/index.mdx
+++ b/src/content/docs/workers/tutorials/store-data-with-fauna/index.mdx
@@ -114,10 +114,16 @@ cd fauna-workers
Update the `wrangler.toml` file to set the name for the Worker.
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
name = "fauna-workers"
```
+
+
### Add your Fauna database key for local development
For local development, add a `.dev.vars` file on the project root and add your Fauna key's secret as a [development secret](/workers/configuration/secrets/#local-development-with-secrets):
diff --git a/src/content/docs/workers/tutorials/upload-assets-with-r2/index.mdx b/src/content/docs/workers/tutorials/upload-assets-with-r2/index.mdx
index faea07c0dff9a21..443be11b1542779 100644
--- a/src/content/docs/workers/tutorials/upload-assets-with-r2/index.mdx
+++ b/src/content/docs/workers/tutorials/upload-assets-with-r2/index.mdx
@@ -68,12 +68,18 @@ After your new R2 bucket is ready, use it inside your Worker application.
Use your R2 bucket inside your Worker project by modifying the `wrangler.toml` configuration file to include an R2 bucket [binding](/workers/runtime-apis/bindings/). Add the following R2 bucket binding to your `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[r2_buckets]]
binding = 'MY_BUCKET'
bucket_name = ''
```
+
+
Give your R2 bucket binding name. Replace `` with the name of the R2 bucket you created earlier.
Your Worker application can now access your R2 bucket using the `MY_BUCKET` variable. You can now perform CRUD (Create, Read, Update, Delete) operations on the contents of the bucket.
diff --git a/src/content/docs/workers/tutorials/workers-kv-from-rust/index.mdx b/src/content/docs/workers/tutorials/workers-kv-from-rust/index.mdx
index 90718cabc4cf4ba..36e5136f475e0c1 100644
--- a/src/content/docs/workers/tutorials/workers-kv-from-rust/index.mdx
+++ b/src/content/docs/workers/tutorials/workers-kv-from-rust/index.mdx
@@ -52,6 +52,10 @@ npx wrangler kv:namespace create cities
To add this configuration to your project, open the `wrangler.toml` file and create an entry for `kv_namespaces` above the build command:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
kv_namespaces = [
{ binding = "cities", id = "e29b263ab50e42ce9b637fa8370175e8" }
@@ -60,6 +64,8 @@ kv_namespaces = [
# build command...
```
+
+
With this configured, you can access the KV namespace with the binding `"cities"` from Rust.
## 3. Write data to KV
diff --git a/src/content/docs/workers/wrangler/api.mdx b/src/content/docs/workers/wrangler/api.mdx
index ed28c395bc614c4..bb4757980db9f94 100644
--- a/src/content/docs/workers/wrangler/api.mdx
+++ b/src/content/docs/workers/wrangler/api.mdx
@@ -297,11 +297,17 @@ const platform = await getPlatformProxy(options);
The `getPlatformProxy` function uses bindings found in `wrangler.toml`. For example, if you have an [environment variable](/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) configuration set up in `wrangler.toml`:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[vars]
MY_VARIABLE = "test"
```
+
+
You can access the bindings by importing `getPlatformProxy` like this:
```js
@@ -336,6 +342,10 @@ The bindings supported by `getPlatformProxy` are:
For example, you might have the following file read by `getPlatformProxy`.
+
+
+
+
```toml
[[durable_objects.bindings]]
name = "MyDurableObject"
@@ -343,6 +353,8 @@ The bindings supported by `getPlatformProxy` are:
script_name = "my-worker"
```
+
+
In order for this binding to be successfully proxied by `getPlatformProxy`, a worker named `my-worker`
with a Durable Object declaration using the same `class_name` of `"MyDurableObject"` must be run
separately via `wrangler dev`.
diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx
index c0e55b0ead6534b..75d49a8805bd489 100644
--- a/src/content/docs/workers/wrangler/commands.mdx
+++ b/src/content/docs/workers/wrangler/commands.mdx
@@ -2483,12 +2483,18 @@ Expires: 1/01/2025
You can then add this certificate as a [binding](/workers/runtime-apis/bindings/) in your `wrangler.toml`:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
mtls_certificates = [
{ binding = "MY_CERT", certificate_id = "99f5fef1-6cc1-46b8-bd79-44a0d5082b8d" }
]
```
+
+
Note that the certificate and private keys must be in separate (typically `.pem`) files when uploading.
### `list`
diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx
index 9e5a14721a763de..10390fecb4fe00a 100644
--- a/src/content/docs/workers/wrangler/configuration.mdx
+++ b/src/content/docs/workers/wrangler/configuration.mdx
@@ -4,23 +4,28 @@ title: Configuration
head:
- tag: title
content: Configuration - Wrangler
-description: Use a `wrangler.toml` configuration file to customize the
+description: Use a configuration file to customize the
development and deployment setup for your Worker project and other Developer
Platform products.
---
import { Render, Type, MetaInfo } from "~/components";
-Wrangler optionally uses a `wrangler.toml` configuration file to customize the development and deployment setup for a Worker.
+Wrangler optionally uses a `wrangler.json`/`wrangler.toml` file to customize the development and deployment setup for a Worker.
-:::caution
+:::note
+
+As of Wrangler v3.91.0 Wrangler supports both JSON (`wrangler.json`) and TOML (`wrangler.toml`) for it's configuration file. Prior to that version, only `wrangler.toml` was supported. The format of Wrangler's configuration file is exactly the same across both languages, except that the syntax is `JSON` rather than `TOML`. Throughout this page and the rest of Cloudflare's documentation config snippets are provided as both JSON and TOML.
-Wrangler currently supports an `--experimental-json-config` flag, which will read your configuration from a `wrangler.json` file, rather than `wrangler.toml`. The format of this file is exactly the same as the `wrangler.toml` configuration file, except that the syntax is `JSON` rather than `TOML`. This is experimental, and is not recommended for production use.
:::
-It is best practice to treat `wrangler.toml` as the [source of truth](#source-of-truth) for configuring a Worker.
+It is best practice to treat Wrangler's configuration file as the [source of truth](#source-of-truth) for configuring a Worker.
+
+## Sample Wrangler configuration
+
+import { WranglerConfig } from "~/components";
-## Sample `wrangler.toml` configuration
+
```toml
# Top-level configuration
@@ -44,6 +49,8 @@ kv_namespaces = [
]
```
+
+
## Environments
The configuration for a Worker can become complex when you define different [environments](/workers/wrangler/environments/), and each environment has its own configuration.
@@ -180,7 +187,7 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d
### Usage model
-As of March 1, 2024 the [usage model](/workers/platform/pricing/#workers) configured in your Worker's `wrangler.toml` will be ignored. The [Standard](/workers/platform/pricing/#example-pricing-standard-usage-model) usage model applies.
+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**.
@@ -238,16 +245,16 @@ There are three types of [routes](/workers/configuration/routing/): [Custom Doma
Example:
-```toml title="wrangler.toml"
-route = { pattern = "example.com", custom_domain = true }
-
-# or
+
+```toml title="wrangler.toml"
routes = [
{ pattern = "shop.example.com", custom_domain = true }
]
```
+
+
### Routes
[Routes](/workers/configuration/routing/routes/) allow users to map a URL pattern to a Worker. A route can be configured as a zone ID route, a zone name route, or a simple route.
@@ -264,12 +271,16 @@ routes = [
Example:
+
+
```toml title="wrangler.toml"
routes = [
{ pattern = "subdomain.example.com/*", zone_id = "" }
]
```
+
+
#### Zone name route
- `pattern`
@@ -282,22 +293,30 @@ routes = [
Example:
+
+
```toml title="wrangler.toml"
routes = [
{ pattern = "subdomain.example.com/*", zone_name = "example.com" }
]
```
+
+
#### Simple route
This is a simple route that only requires a pattern.
Example:
+
+
```toml title="wrangler.toml"
route = "example.com/*"
```
+
+
### `workers.dev`
Cloudflare Workers accounts come with a `workers.dev` subdomain that is configurable in the Cloudflare dashboard.
@@ -306,10 +325,14 @@ Cloudflare Workers accounts come with a `workers.dev` subdomain that is configur
- Whether the Worker runs on a custom `workers.dev` account subdomain. Defaults to `true`.
+
+
```toml title="wrangler.toml"
workers_dev = false
```
+
+
## Triggers
Triggers allow you to define the `cron` expression to invoke your Worker's `scheduled` function. Refer to [Supported cron expressions](/workers/configuration/cron-triggers/#supported-cron-expressions).
@@ -321,11 +344,15 @@ Triggers allow you to define the `cron` expression to invoke your Worker's `sche
Example:
+
+
```toml title="wrangler.toml"
[triggers]
crons = ["* * * * *"]
```
+
+
## Observability
The [Observability](/workers/observability/logs/workers-logs) setting allows you to automatically ingest, store, filter, and analyze logging data emitted from Cloudflare Workers directly from your Cloudflare Worker's dashboard.
@@ -339,12 +366,15 @@ The [Observability](/workers/observability/logs/workers-logs) setting allows you
Example:
+
+
```toml title="wrangler.toml"
[observability]
enabled = true
head_sampling_rate = 0.1 # 10% of requests are logged
```
+
## Custom builds
@@ -364,6 +394,8 @@ You can configure a custom build step that will be run before your Worker is dep
Example:
+
+
```toml title="wrangler.toml"
[build]
command = "npm run build"
@@ -371,6 +403,8 @@ cwd = "build_cwd"
watch_dir = "build_watch_dir"
```
+
+
## Limits
You can impose limits on your Worker's behavior at runtime. Limits are only supported for the [Standard Usage Model](/workers/platform/pricing/#example-pricing-standard-usage-model). Limits are only enforced when deployed to Cloudflare's network, not in local development. The CPU limit can be set to a maximum of 30,000 milliseconds (30 seconds).
@@ -383,11 +417,15 @@ You can impose limits on your Worker's behavior at runtime. Limits are only supp
Example:
+
+
```toml title="wrangler.toml"
[limits]
cpu_ms = 100
```
+
+
## Bindings
### Browser Rendering
@@ -402,15 +440,15 @@ A [browser binding](/workers/runtime-apis/bindings/) will provide your Worker wi
Example:
-```toml title="wrangler.toml"
-browser = { binding = "" }
-
-# or
+
+```toml title="wrangler.toml"
[browser]
binding = ""
```
+
+
### D1 databases
[D1](/d1/) is Cloudflare's serverless SQL database. A Worker can query a D1 database (or databases) by creating a [binding](/workers/runtime-apis/bindings/) to each database for D1's [client API](/d1/build-with-d1/d1-client-api/).
@@ -447,19 +485,17 @@ When using Wrangler in the default local development mode, files will be written
Example:
-```toml title="wrangler.toml"
-d1_databases = [
- { binding = "", database_name = "", database_id = "" }
-]
-
-# or
+
+```toml title="wrangler.toml"
[[d1_databases]]
binding = ""
database_name = ""
database_id = ""
```
+
+
### Dispatch namespace bindings (Workers for Platforms)
Dispatch namespace bindings allow for communication between a [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) and a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace). Dispatch namespace bindings are used in [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/). Workers for Platforms helps you deploy serverless functions programmatically on behalf of your customers.
@@ -477,6 +513,8 @@ Dispatch namespace bindings allow for communication between a [dynamic dispatch
- `service` The name of the [outbound Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/) to bind to.
- `parameters` array optional A list of parameters to pass data from your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) to the [outbound Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/).
+
+
```toml title="wrangler.toml"
[[dispatch_namespaces]]
binding = ""
@@ -485,6 +523,8 @@ outbound = {service = "", parameters = ["params_object"]}
```
+
+
### Durable Objects
[Durable Objects](/durable-objects/) provide low-latency coordination and consistent storage for the Workers platform.
@@ -509,19 +549,17 @@ To bind Durable Objects to your Worker, assign an array of the below object to t
Example:
-```toml title="wrangler.toml"
-durable_objects.bindings = [
- { name = "", class_name = "" }
-]
-
-# or
+
+```toml title="wrangler.toml"
[[durable_objects.bindings]]
name = ""
class_name = ""
```
+
+
#### Migrations
When making changes to your Durable Object classes, you must perform a migration. Refer to [Durable Object migrations](/durable-objects/reference/durable-objects-migrations/).
@@ -544,6 +582,8 @@ When making changes to your Durable Object classes, you must perform a migration
Example:
+
+
```toml title="wrangler.toml"
[[migrations]]
tag = "v1" # Should be unique for each entry
@@ -555,6 +595,8 @@ renamed_classes = [{from = "DurableObjectExample", to = "UpdatedName" }] # Array
deleted_classes = ["DeprecatedClass"] # Array of deleted class names
```
+
+
### Email bindings
+
```toml title="wrangler.toml"
# required for database drivers to function
compatibility_flags = ["nodejs_compat_v2"]
@@ -610,6 +654,8 @@ binding = ""
id = ""
```
+
+
### KV namespaces
[Workers KV](/kv/api/) is a global, low-latency, key-value data store. It stores data in a small number of centralized data centers, then caches that data in Cloudflare’s data centers after access.
@@ -636,14 +682,9 @@ When using Wrangler in the default local development mode, files will be written
Example:
-```toml title="wrangler.toml"
-kv_namespaces = [
- { binding = "", id = "" },
- { binding = "", id = "" }
-]
-
-# or
+
+```toml title="wrangler.toml"
[[kv_namespaces]]
binding = ""
id = ""
@@ -653,6 +694,8 @@ binding = ""
id = ""
```
+
+
### Queues
[Queues](/queues/) is Cloudflare's global message queueing service, providing [guaranteed delivery](/queues/reference/delivery-guarantees/) and [message batching](/queues/configuration/batching-retries/). To interact with a queue with Workers, you need a producer Worker to send messages to the queue and a consumer Worker to pull batches of messages out of the Queue. A single Worker can produce to and consume from multiple Queues.
@@ -673,6 +716,8 @@ To bind Queues to your producer Worker, assign an array of the below object to t
Example:
+
+
```toml title="wrangler.toml"
[[queues.producers]]
binding = ""
@@ -680,6 +725,8 @@ Example:
delivery_delay = 60 # Delay messages by 60 seconds before they are delivered to a consumer
```
+
+
To bind Queues to your consumer Worker, assign an array of the below object to the `[[queues.consumers]]` key.
- `queue`
@@ -715,6 +762,8 @@ To bind Queues to your consumer Worker, assign an array of the below object to t
Example:
+
+
```toml title="wrangler.toml"
[[queues.consumers]]
queue = "my-queue"
@@ -726,6 +775,8 @@ Example:
retry_delay = 120 # Delay retried messages by 2 minutes before re-attempting delivery
```
+
+
### R2 buckets
[Cloudflare R2 Storage](/r2) allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.
@@ -756,14 +807,9 @@ When using Wrangler in the default local development mode, files will be written
Example:
-```toml title="wrangler.toml"
-r2_buckets = [
- { binding = "", bucket_name = ""},
- { binding = "", bucket_name = ""}
-]
-
-# or
+
+```toml title="wrangler.toml"
[[r2_buckets]]
binding = ""
bucket_name = ""
@@ -773,6 +819,8 @@ binding = ""
bucket_name = ""
```
+
+
### Vectorize indexes
A [Vectorize index](/vectorize/) allows you to insert and query vector embeddings for semantic search, classification and other vector search use-cases.
@@ -789,18 +837,16 @@ To bind Vectorize indexes to your Worker, assign an array of the below object to
Example:
-```toml title="wrangler.toml"
-vectorize = [
- { binding = "", index_name = ""}
-]
-
-# or
+
+```toml title="wrangler.toml"
[[vectorize]]
binding = ""
index_name = ""
```
+
+
### Service bindings
A service binding allows you to send HTTP requests to another Worker without those requests going over the Internet. The request immediately invokes the downstream Worker, reducing latency as compared to a request to a third-party service. Refer to [About Service Bindings](/workers/runtime-apis/bindings/service-bindings/).
@@ -821,19 +867,17 @@ To bind other Workers to your Worker, assign an array of the below object to the
Example:
-```toml title="wrangler.toml"
-services = [
- { binding = "", service = "", entrypoint = "" }
-]
-
-# or
+
+```toml title="wrangler.toml"
[[services]]
binding = ""
service = ""
entrypoint = ""
```
+
+
### Static assets
Refer to [Assets](#assets).
@@ -854,16 +898,16 @@ To bind Analytics Engine datasets to your Worker, assign an array of the below o
Example:
-```toml
-analytics_engine_datasets = [{ binding = "", dataset = "" }]
-
-# or
+
+```toml
[[analytics_engine_datasets]]
binding = ""
dataset = ""
```
+
+
### mTLS Certificates
To communicate with origins that require client authentication, a Worker can present a certificate for mTLS in subrequests. Wrangler provides the `mtls-certificate` [command](/workers/wrangler/commands#mtls-certificate) to upload and manage these certificates.
@@ -878,16 +922,11 @@ To create a [binding](/workers/runtime-apis/bindings/) to an mTLS certificate fo
- The ID of the certificate. Wrangler displays this via the `mtls-certificate upload` and `mtls-certificate list` commands.
-Example of a `wrangler.toml` configuration that includes an mTLS certificate binding:
+Example of a Wrangler configuration file that includes an mTLS certificate binding:
-```toml title="wrangler.toml"
-mtls_certificates = [
- { binding = "", certificate_id = "" },
- { binding = "", certificate_id = "" }
-]
-
-# or
+
+```toml title="wrangler.toml"
[[mtls_certificates]]
binding = ""
certificate_id = ""
@@ -897,6 +936,8 @@ binding = ""
certificate_id = ""
```
+
+
mTLS certificate bindings can then be used at runtime to communicate with secured origins via their [`fetch` method](/workers/runtime-apis/bindings/mtls).
### Workers AI
@@ -914,15 +955,15 @@ Unlike other bindings, this binding is limited to one AI binding per Worker proj
Example:
-```toml
-ai = { binding = "" }
-
-# or
+
+```toml
[ai]
binding = "AI" # available in your Worker code on `env.AI`
```
+
+
## Assets
[Static assets](/workers/static-assets/) allows developers to run front-end websites on Workers. You can configure the directory of assets, an optional runtime binding, and routing configuration options.
@@ -949,10 +990,14 @@ The following options are available under the `assets` key.
Example:
+
+
```toml title="wrangler.toml"
assets = { directory = "./public", binding = "ASSETS", html_handling = "force-trailing-slash", not_found_handling = "404-page" }
```
+
+
## Bundling
Wrangler can operate in two modes: the default bundling mode and `--no-bundle` mode.
@@ -977,12 +1022,16 @@ The `rules` key will be an array of the below object.
Example:
+
+
```toml title="wrangler.toml"
rules = [
{ type = "Text", globs = ["**/*.md"], fallthrough = true }
]
```
+
+
### Importing modules within a Worker
You can import and refer to these modules within your Worker, like so:
@@ -1032,6 +1081,8 @@ You can configure various aspects of local development, such as the local protoc
Example:
+
+
```toml title="wrangler.toml"
[dev]
ip = "192.168.1.1"
@@ -1039,6 +1090,8 @@ port = 8080
local_protocol = "http"
```
+
+
### Secrets
[Secrets](/workers/configuration/secrets/) are a type of binding that allow you to [attach encrypted text values](/workers/wrangler/commands/#secret) to your Worker.
@@ -1049,11 +1102,15 @@ local_protocol = "http"
You can configure Wrangler to replace all calls to import a particular package with a module of your choice, by configuring the `alias` field:
+
+
```toml title="wrangler.toml"
[alias]
"foo" = "./replacement-module-filepath"
```
+
+
```js title="replacement-module-filepath.js"
export const bar = "baz";
```
@@ -1076,11 +1133,15 @@ For example, some NPM packages depend on [`node-fetch`](https://www.npmjs.com/pa
You can alias all imports of `node-fetch` to instead point directly to the `fetch()` API that is built into the Workers runtime:
+
+
```toml title="wrangler.toml"
[alias]
"node-fetch" = "./fetch-nolyfill"
```
+
+
```js title="./fetch-nolyfill"
export default fetch;
```
@@ -1091,11 +1152,15 @@ You can use module aliasing to provide your own polyfill implementation of a Nod
For example, let’s say the NPM package you rely on calls [`fs.readFile`](https://nodejs.org/api/fs.html#fsreadfilepath-options-callback). You can alias the fs module by adding the following to your Worker’s wrangler.toml:
+
+
```toml title="wrangler.toml"
[alias]
"fs" = "./fs-polyfill"
```
+
+
```js title="./fs-polyfill"
export function readFile() {
// ...
@@ -1114,11 +1179,15 @@ In many cases, this allows you to work provide just enough of an API to make a d
Example:
+
+
```toml title="wrangler.toml"
upload_source_maps = true
```
+
+
## Workers Sites
:::note[Cloudflare Pages]
@@ -1130,7 +1199,7 @@ Consider using [Cloudflare Pages](/pages/) for hosting static applications inste
- `bucket`
- - The directory containing your static assets. It must be a path relative to your `wrangler.toml` file.
+ - The directory containing your static assets. It must be a path relative to your Wrangler configuration file.
- `include`
@@ -1142,6 +1211,8 @@ Consider using [Cloudflare Pages](/pages/) for hosting static applications inste
Example:
+
+
```toml title="wrangler.toml"
[site]
bucket = "./public"
@@ -1149,6 +1220,8 @@ include = ["upload_dir"]
exclude = ["ignore_dir"]
```
+
+
## Proxy support
Corporate networks will often have proxies on their networks and this can sometimes cause connectivity issues. To configure Wrangler with the appropriate proxy details, use the below environmental variables:
@@ -1172,12 +1245,12 @@ For example, if both `https_proxy` and `http_proxy` are set, Wrangler will only
## Source of truth
-We recommend treating your `wrangler.toml` file as the source of truth for your Worker configuration, and to avoid making changes to your Worker via the Cloudflare dashboard if you are using Wrangler.
+We recommend treating your Wrangler configuration file as the source of truth for your Worker configuration, and to avoid making changes to your Worker via the Cloudflare dashboard if you are using Wrangler.
-If you need to make changes to your Worker from the Cloudflare dashboard, the dashboard will generate a TOML snippet for you to copy into your `wrangler.toml` file, which will help ensure your `wrangler.toml` file is always up to date.
+If you need to make changes to your Worker from the Cloudflare dashboard, the dashboard will generate a TOML snippet for you to copy into your Wrangler configuration file, which will help ensure your Wrangler configuration file is always up to date.
-If you change your environment variables in the Cloudflare dashboard, Wrangler will override them the next time you deploy. If you want to disable this behavior, add `keep_vars = true` to your `wrangler.toml`.
+If you change your environment variables in the Cloudflare dashboard, Wrangler will override them the next time you deploy. If you want to disable this behavior, add `keep_vars = true` to your Wrangler configuration file.
-If you change your routes in the dashboard, Wrangler will override them in the next deploy with the routes you have set in your `wrangler.toml`. To manage routes via the Cloudflare dashboard only, remove any route and routes keys from your `wrangler.toml` file. Then add `workers_dev = false` to your `wrangler.toml` file. For more information, refer to [Deprecations](/workers/wrangler/deprecations/#other-deprecated-behavior).
+If you change your routes in the dashboard, Wrangler will override them in the next deploy with the routes you have set in your Wrangler configuration file. To manage routes via the Cloudflare dashboard only, remove any route and routes keys from your Wrangler configuration file. Then add `workers_dev = false` to your Wrangler configuration file. For more information, refer to [Deprecations](/workers/wrangler/deprecations/#other-deprecated-behavior).
Wrangler will not delete your secrets (encrypted environment variables) unless you run `wrangler secret delete `.
diff --git a/src/content/docs/workers/wrangler/custom-builds.mdx b/src/content/docs/workers/wrangler/custom-builds.mdx
index fb6c4e4648da342..68c65b1e3a84712 100644
--- a/src/content/docs/workers/wrangler/custom-builds.mdx
+++ b/src/content/docs/workers/wrangler/custom-builds.mdx
@@ -12,7 +12,7 @@ Custom builds are a way for you to customize how your code is compiled, before b
:::note
-With the release of Wrangler v2, it is no longer necessary to use custom builds to bundle your code via webpack and similar bundlers. Wrangler runs [esbuild](https://esbuild.github.io/) by default as part of the `dev` and `publish` commands, and bundles your Worker project into a single Worker script. Refer to [Bundling](/workers/wrangler/bundling/).
+With the release of Wrangler v2, it is no longer necessary to use custom builds to bundle your code via webpack and similar bundlers. Wrangler runs [esbuild](https://esbuild.github.io/) by default as part of the `dev` and `publish` commands, and bundles your Worker project into a single Worker script. Refer to [Bundling](/workers/wrangler/bundling/).
:::
## Configure custom builds
@@ -37,9 +37,15 @@ Custom builds are configured by adding a `[build]` section in your `wrangler.tom
Example:
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
[build]
command = "npm run build"
cwd = "build_cwd"
watch_dir = "build_watch_dir"
```
+
+
diff --git a/src/content/docs/workers/wrangler/environments.mdx b/src/content/docs/workers/wrangler/environments.mdx
index 2670abbc1202a12..e1942675f2c7502 100644
--- a/src/content/docs/workers/wrangler/environments.mdx
+++ b/src/content/docs/workers/wrangler/environments.mdx
@@ -33,6 +33,10 @@ Be careful when naming your environments that they do not contain sensitive info
Review the layout of an example `[env.dev]` environment that sets up a custom `dev.example.com` route:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "your-worker"
route = "example.com"
@@ -41,6 +45,8 @@ route = "example.com"
route = "dev.example.com"
```
+
+
You cannot specify multiple environments with the same name.
Wrangler appends the environment name to the top-level name to deploy a Worker. For example, a Worker project named `my-worker` with an environment `[env.dev]` would deploy a Worker named `my-worker-dev`.
@@ -55,6 +61,10 @@ After you have configured your environment, run `npx wrangler deploy` in your Wo
Review the following example `wrangler.toml` file:
+
+
+
+
```toml
name = "my-worker"
@@ -73,6 +83,8 @@ kv_namespaces = [
]
```
+
+
You may assign environment-specific [secrets](/workers/configuration/secrets/) by running the command [`wrangler secret put -env`](/workers/wrangler/commands/#put-3).
---
@@ -83,6 +95,10 @@ You may assign environment-specific [secrets](/workers/configuration/secrets/) b
The following `wrangler.toml` file adds two environments, `[env.staging]` and `[env.production]`, to the `wrangler.toml` file. If you are deploying to a [Custom Domain](/workers/configuration/routing/custom-domains/) or [route](/workers/configuration/routing/routes/), you must provide a [`route` or `routes` key](/workers/wrangler/configuration/) for each environment.
+
+
+
+
```toml
name = "my-worker"
route = "dev.example.com/*"
@@ -100,6 +116,8 @@ routes = [
]
```
+
+
In order to use environments with this configuration, you can pass the name of the environment via the `--env` flag.
With this configuration, Wrangler will behave in the following manner:
@@ -150,6 +168,10 @@ if (ENVIRONMENT === "staging") {
To deploy your code to your `*.workers.dev` subdomain, include `workers_dev = true` in the desired environment. Your `wrangler.toml` file may look like this:
+
+
+
+
```toml
name = "my-worker"
route = "example.com/*"
@@ -158,6 +180,8 @@ route = "example.com/*"
workers_dev = true
```
+
+
With this configuration, Wrangler will behave in the following manner:
```sh
diff --git a/src/content/docs/workers/wrangler/migration/v1-to-v2/eject-webpack.mdx b/src/content/docs/workers/wrangler/migration/v1-to-v2/eject-webpack.mdx
index 33ffbf6c520b3da..50df7436f2d3fb5 100644
--- a/src/content/docs/workers/wrangler/migration/v1-to-v2/eject-webpack.mdx
+++ b/src/content/docs/workers/wrangler/migration/v1-to-v2/eject-webpack.mdx
@@ -103,16 +103,26 @@ module.exports = {
Remove the `type` and `webpack_config` keys from your `wrangler.toml` file, as they are not supported anymore.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
# Remove these!
type = "webpack"
webpack_config = "webpack.config.js"
```
+
+
5. Tell Wrangler how to bundle your Worker.
Wrangler no longer has any knowledge of how to build your Worker. You will need to tell it how to call webpack and where to look for webpack's output. This translates into two fields:
+
+
+
+
```toml
main = "./worker/script.js" # by default, or whatever file webpack outputs
[build]
@@ -120,6 +130,8 @@ command = "npm run build" # or "yarn build"
# ...
```
+
+
6. Test your project.
Try running `npx wrangler deploy` to test that your configuration works as expected.
diff --git a/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/commands.mdx b/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/commands.mdx
index 16eeb3d5a34247e..bb44e288340cdd9 100644
--- a/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/commands.mdx
+++ b/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/commands.mdx
@@ -492,6 +492,10 @@ one for staging and one for production).
A `wrangler.toml` file with two environments:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[env.staging]
kv_namespaces = [
@@ -504,6 +508,8 @@ kv_namespaces = [
]
```
+
+
To insert a value into a specific KV namespace, you can use:
```sh
@@ -536,6 +542,10 @@ Most `kv` commands require you to specify a namespace. A namespace can be specif
Most `kv` subcommands also allow you to specify an environment with the optional `--env` flag. This allows you to publish Workers running the same code but with different namespaces. For example, you could use separate staging and production namespaces for KV data in your `wrangler.toml` file:
+
+
+
+
```toml
type = "webpack"
name = "my-worker"
@@ -554,6 +564,8 @@ kv_namespaces = [
]
```
+
+
With the `wrangler.toml` file above, you can specify `--env production` when you want to perform a KV action on the namespace `MY_KV` under `env.production`. For example, with the `wrangler.toml` file above, you can get a value out of a production KV instance with:
```sh
diff --git a/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration.mdx b/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration.mdx
index f00cc40a917723a..3195e9494faa927 100644
--- a/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration.mdx
+++ b/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration.mdx
@@ -25,6 +25,10 @@ The top-level configuration is the collection of values you specify at the top o
The layout of a top-level configuration in a `wrangler.toml` file is displayed below:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "your-worker"
type = "javascript"
@@ -42,6 +46,8 @@ zone_id = "your-zone-id"
routes = ["example.com/*"]
```
+
+
Environment configuration (optional): the configuration values you specify under an `[env.name]` in your `wrangler.toml` file.
Environments allow you to deploy the same project to multiple places under multiple names. These environments are utilized with the `--env` or `-e` flag on the [commands](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/commands/) that are deploying live Workers:
@@ -56,6 +62,10 @@ Some environment properties can be [*inherited*](#keys) from the top-level confi
An example of an `[env.name]` configuration looks like this:
+
+
+
+
```toml
type = "javascript"
@@ -66,9 +76,10 @@ account_id = "your-account-id"
FOO = "default FOO value"
BAR = "default BAR value"
-kv_namespaces = [
- { binding = "FOO", id = "1a...", preview_id = "1b..." }
-]
+[[kv_namespaces]]
+binding = "FOO"
+id = "1a..."
+preview_id = "1b..."
[env.helloworld]
# Now adding configuration keys for the "helloworld" environment.
@@ -76,17 +87,20 @@ kv_namespaces = [
name = "your-worker-helloworld"
account_id = "your-other-account-id"
-[vars]
+[env.helloworld.vars]
FOO = "env-helloworld FOO value"
BAR = "env-helloworld BAR value"
-kv_namespaces = [
+[[env.helloworld.kv_namespaces]]
# Redeclare kv namespace bindings for each environment
# NOTE: In this case, passing new IDs because new `account_id` value.
- { binding = "FOO", id = "888...", preview_id = "999..." }
-]
+binding = "FOO"
+id = "888..."
+preview_id = "999..."
```
+
+
To deploy this example Worker to the `helloworld` environment, you would run `wrangler publish --env helloworld`.
***
@@ -179,12 +193,18 @@ The `vars` key defines a table of [environment variables](/workers/configuration
Usage:
+
+
+
+
```toml
[vars]
FOO = "some value"
BAR = "some other string"
```
+
+
The table keys are available to your Worker as global variables, which will contain their associated values.
```js
@@ -198,10 +218,16 @@ console.log(BAR);
Alternatively, you can define `vars` using an inline table format. This style should not include any new lines to be considered a valid TOML configuration:
+
+
+
+
```toml
vars = { FOO = "some value", BAR = "some other string" }
```
+
+
:::note
@@ -216,6 +242,10 @@ Secrets should be handled using the [`wrangler secret`](/workers/wrangler/comman
Usage:
+
+
+
+
```toml
kv_namespaces = [
{ binding = "FOO", id = "0f2ac74b498b48028cb68387c421e279", preview_id = "6a1ddb03f3ec250963f0a1e46820076f" },
@@ -223,8 +253,14 @@ kv_namespaces = [
]
```
+
+
Alternatively, you can define `kv namespaces` like so:
+
+
+
+
```toml
[[kv_namespaces]]
binding = "FOO"
@@ -237,6 +273,8 @@ preview_id = "xyz456"
id = "xyz123"
```
+
+
Much like environment variables and secrets, the `binding` names are available to your Worker as global variables.
```js
@@ -280,12 +318,18 @@ A [Workers Site](/workers/configuration/sites/start-from-scratch) generated with
Usage:
+
+
+
+
```toml
[site]
bucket = "./public"
entry-point = "workers-site"
```
+
+
* `bucket` required
@@ -317,6 +361,10 @@ For exceptionally large pages, Workers Sites may not be ideal. There is a 25 MiB
If you want to include only a certain set of files or directories in your `bucket`, add an `include` field to your
`[site]` section of your `wrangler.toml` file:
+
+
+
+
```toml
[site]
bucket = "./public"
@@ -324,12 +372,18 @@ entry-point = "workers-site"
include = ["included_dir"] # must be an array.
```
+
+
Wrangler will only upload files or directories matching the patterns in the `include` array.
#### Excluding files/directories
If you want to exclude files or directories in your `bucket`, add an `exclude` field to your `[site]` section of your `wrangler.toml` file:
+
+
+
+
```toml
[site]
bucket = "./public"
@@ -337,6 +391,8 @@ entry-point = "workers-site"
exclude = ["excluded_dir"] # must be an array.
```
+
+
Wrangler will ignore files or directories matching the patterns in the `exclude` array when uploading assets to Workers KV.
#### Include > Exclude
@@ -367,11 +423,17 @@ A set of cron triggers used to call a Worker on a schedule.
Usage:
+
+
+
+
```toml
[triggers]
crons = ["0 0 * JAN-JUN FRI", "0 0 LW JUL-DEC *"]
```
+
+
* `crons` optional
@@ -385,12 +447,18 @@ Arguments for `wrangler dev` can be configured here so you do not have to repeat
Usage:
+
+
+
+
```toml
[dev]
port = 9000
local_protocol = "https"
```
+
+
* `ip` optional
@@ -427,6 +495,10 @@ addEventListener("fetch", (event) => {
Usage:
+
+
+
+
```toml
[build]
command = "npm install && npm run build"
@@ -435,6 +507,8 @@ command = "npm install && npm run build"
format = "service-worker"
```
+
+
##### `[build]`
@@ -506,6 +580,10 @@ export default {
To create a Workers project using Wrangler and Modules, add a `[build]` section:
+
+
+
+
```toml
[build]
command = "npm install && npm run build"
@@ -515,6 +593,8 @@ format = "modules"
main = "./worker.mjs"
```
+
+
##### `[build]`
@@ -565,6 +645,10 @@ If your project is written using CommonJS modules, you will need to re-export yo
Defaults:
+
+
+
+
```toml
[build.upload]
format = "modules"
@@ -582,6 +666,8 @@ type = "CommonJS"
globs = ["**/*.js", "**/*.cjs"]
```
+
+
* `type` required
* The module type, see the table below for acceptable options:
@@ -602,6 +688,10 @@ globs = ["**/*.js", "**/*.cjs"]
To illustrate how these levels are applied, here is a `wrangler.toml` file using multiple environments:
+
+
+
+
```toml
# top level configuration
type = "javascript"
@@ -647,3 +737,5 @@ kv_namespaces = [
{ binding = "BAR", id = "0d8c101e168d03c65bddf4ba75150f33" }
]
```
+
+
diff --git a/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/webpack.mdx b/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/webpack.mdx
index d496d244a0fbbff..2754befc007e9fe 100644
--- a/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/webpack.mdx
+++ b/src/content/docs/workers/wrangler/migration/v1-to-v2/wrangler-legacy/webpack.mdx
@@ -51,6 +51,10 @@ module.exports = {
};
```
+import { WranglerConfig } from "~/components";
+
+
+
```toml
type = "webpack"
name = "my-worker"
@@ -59,10 +63,16 @@ workers_dev = true
webpack_config = "webpack.config.js"
```
+
+
### Example with multiple environments
It is possible to use different webpack configuration files within different [Wrangler environments](/workers/wrangler/environments/). For example, the `"webpack.development.js"` configuration file is used during `wrangler dev` for development, but other, more production-ready configurations are used when building for the staging or production environments:
+
+
+
+
```toml
type = "webpack"
name = "my-worker-dev"
@@ -79,6 +89,8 @@ name = "my-worker-production"
webpack_config = "webpack.production.js"
```
+
+
```js
module.exports = {
target: 'webworker',
diff --git a/src/content/docs/workflows/build/trigger-workflows.mdx b/src/content/docs/workflows/build/trigger-workflows.mdx
index 1bd5cbe0ef5a601..5109bc870d313ec 100644
--- a/src/content/docs/workflows/build/trigger-workflows.mdx
+++ b/src/content/docs/workflows/build/trigger-workflows.mdx
@@ -31,6 +31,10 @@ New to Workflows? Start with the [Workflows tutorial](/workflows/get-started/gui
To bind to a Workflow from your Workers code, you need to define a [binding](/workers/wrangler/configuration/) to a specific Workflow. For example, to bind to the Workflow defined in the [get started guide](/workflows/get-started/guide/), you would configure a `wrangler.toml` with the below:
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
name = "workflows-tutorial"
main = "src/index.ts"
@@ -47,6 +51,8 @@ binding = "MY_WORKFLOW"
class_name = "MyWorkflow"
```
+
+
The `binding = "MY_WORKFLOW"` line defines the JavaScript variable that our Workflow methods are accessible on, including `create` (which triggers a new instance) or `get` (which returns the status of an existing instance).
The following example shows how you can manage Workflows from within a Worker, including:
diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx
index 1b48851d49bbb6b..189dff5c02d1633 100644
--- a/src/content/docs/workflows/build/workers-api.mdx
+++ b/src/content/docs/workflows/build/workers-api.mdx
@@ -107,6 +107,10 @@ You can bind to a Workflow by defining a `[[workflows]]` binding within your `wr
For example, to bind to a Workflow called `workflows-starter` and to make it available on the `MY_WORKFLOW` variable to your Worker script, you would configure the following fields within the `[[workflows]]` binding definition:
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
#:schema node_modules/wrangler/config-schema.json
name = "workflows-starter"
@@ -122,12 +126,18 @@ binding = "MY_WORKFLOW"
class_name = "MyWorkflow"
```
+
+
### Cross-script calls
You can also bind to a Workflow that is defined in a different Worker script from the script your Workflow definition is in. To do this, provide the `script_name` key with the name of the script to the `[[workflows]]` binding definition in your `wrangler.toml` configuration.
For example, if your Workflow is defined in a Worker script named `billing-worker`, but you are calling it from your `web-api-worker` script, your `wrangler.toml` would resemble the following:
+
+
+
+
```toml title="wrangler.toml"
#:schema node_modules/wrangler/config-schema.json
name = "web-api-worker"
@@ -146,6 +156,8 @@ class_name = "MyWorkflow"
script_name = "billing-worker"
```
+
+
## Workflow
:::note
diff --git a/src/content/docs/workflows/examples/send-invoices.mdx b/src/content/docs/workflows/examples/send-invoices.mdx
index 90c9fbc3d47559e..1a7d592a647ed3e 100644
--- a/src/content/docs/workflows/examples/send-invoices.mdx
+++ b/src/content/docs/workflows/examples/send-invoices.mdx
@@ -203,6 +203,10 @@ Here's a minimal package.json:
And finally wrangler.toml:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "cart-invoices"
main = "src/index.ts"
@@ -216,4 +220,6 @@ class_name = "cartInvoicesWorkflow"
[[send_email]]
name = "SEND_EMAIL"
-```
\ No newline at end of file
+```
+
+
\ No newline at end of file
diff --git a/src/content/docs/workflows/get-started/cli-quick-start.mdx b/src/content/docs/workflows/get-started/cli-quick-start.mdx
index c5b41a89a2ab0bf..f6eac46158a063c 100644
--- a/src/content/docs/workflows/get-started/cli-quick-start.mdx
+++ b/src/content/docs/workflows/get-started/cli-quick-start.mdx
@@ -172,6 +172,10 @@ You can [bind to a Workflow](/workers/runtime-apis/bindings/#what-is-a-binding)
To bind a Workflow to a Worker, you need to define a `[[workflows]]` binding in your `wrangler.toml` configuration:
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
[[workflows]]
# name of your workflow
@@ -182,6 +186,8 @@ binding = "MY_WORKFLOW"
class_name = "MyWorkflow"
```
+
+
You can then invoke the methods on this binding directly from your Worker script's `env` parameter. The `Workflow` type has methods for:
* `create()` - creating (triggering) a new instance of the Workflow, returning the ID.
diff --git a/src/content/docs/workflows/get-started/guide.mdx b/src/content/docs/workflows/get-started/guide.mdx
index d8f53a085318e58..47a0d729fa21f92 100644
--- a/src/content/docs/workflows/get-started/guide.mdx
+++ b/src/content/docs/workflows/get-started/guide.mdx
@@ -185,6 +185,10 @@ Before you can deploy a Workflow, you need to configure it.
Open the `wrangler.toml` file at the root of your `workflows-starter` folder, which contains the following `[[workflows]]` configuration:
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
#:schema node_modules/wrangler/config-schema.json
name = "workflows-starter"
@@ -200,6 +204,8 @@ binding = "MY_WORKFLOW"
class_name = "MyWorkflow"
```
+
+
:::note
If you have changed the name of the Workflow in your Wrangler commands, the JavaScript class name, or the name of the project you created, ensure that you update the values above to match the changes.
diff --git a/src/content/partials/email-routing/types-bindings.mdx b/src/content/partials/email-routing/types-bindings.mdx
index 93a1b8db35ea731..c3bf575e744b997 100644
--- a/src/content/partials/email-routing/types-bindings.mdx
+++ b/src/content/partials/email-routing/types-bindings.mdx
@@ -5,6 +5,10 @@
You can add one or more types of bindings to your `wrangler.toml` file. However, each attribute must be on its own line:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
send_email = [
{name = ""},
@@ -12,3 +16,5 @@ send_email = [
{name = "", allowed_destination_addresses = ["@example.com", "@example.com"]},
]
```
+
+
diff --git a/src/content/partials/hyperdrive/create-hyperdrive-binding.mdx b/src/content/partials/hyperdrive/create-hyperdrive-binding.mdx
index fe6873542661438..a65cce7c0f8d66d 100644
--- a/src/content/partials/hyperdrive/create-hyperdrive-binding.mdx
+++ b/src/content/partials/hyperdrive/create-hyperdrive-binding.mdx
@@ -7,12 +7,18 @@ You must create a binding for your Worker to connect to your Hyperdrive configur
To bind your Hyperdrive configuration to your Worker, add the following to the end of your `wrangler.toml` file:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
[[hyperdrive]]
binding = "HYPERDRIVE"
id = "" # the ID associated with the Hyperdrive you just created
```
+
+
Specifically:
- The value (string) you set for the `name` (binding name) will be used to reference this database in your Worker. In this tutorial, name your binding `HYPERDRIVE`.
diff --git a/src/content/partials/hyperdrive/create-hyperdrive-config.mdx b/src/content/partials/hyperdrive/create-hyperdrive-config.mdx
index f452cd458233f55..bf8c4e8dc386104 100644
--- a/src/content/partials/hyperdrive/create-hyperdrive-config.mdx
+++ b/src/content/partials/hyperdrive/create-hyperdrive-config.mdx
@@ -31,6 +31,10 @@ Hyperdrive will attempt to connect to your database with the provided credential
This command outputs a binding for `wrangler.toml`:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "hyperdrive-example"
main = "src/index.ts"
@@ -43,6 +47,8 @@ binding = "HYPERDRIVE"
id = ""
```
+
+
Install the driver:
```sh
diff --git a/src/content/partials/workers/envvar-example.mdx b/src/content/partials/workers/envvar-example.mdx
index b0d7d0302b102f1..d50800843966011 100644
--- a/src/content/partials/workers/envvar-example.mdx
+++ b/src/content/partials/workers/envvar-example.mdx
@@ -3,6 +3,10 @@
---
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "my-worker-dev"
@@ -11,3 +15,5 @@ API_HOST = "example.com"
API_ACCOUNT_ID = "example_user"
SERVICE_X_DATA = { URL = "service-x-api.dev.example", MY_ID = 123 }
```
+
+
diff --git a/src/content/partials/workers/nodejs-compat-wrangler-toml.mdx b/src/content/partials/workers/nodejs-compat-wrangler-toml.mdx
index acf781cf90de59a..f653ee30d354401 100644
--- a/src/content/partials/workers/nodejs-compat-wrangler-toml.mdx
+++ b/src/content/partials/workers/nodejs-compat-wrangler-toml.mdx
@@ -3,6 +3,10 @@
---
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
# other fields elided
#
@@ -10,3 +14,5 @@
compatibility_flags = [ "nodejs_compat" ]
compatibility_date = "2024-09-23"
```
+
+
diff --git a/src/content/partials/workers/service-binding-rpc-example.mdx b/src/content/partials/workers/service-binding-rpc-example.mdx
index b71193ef28766d6..7dd5b874c29f89f 100644
--- a/src/content/partials/workers/service-binding-rpc-example.mdx
+++ b/src/content/partials/workers/service-binding-rpc-example.mdx
@@ -5,23 +5,33 @@
For example, if Worker B implements the public method `add(a, b)`:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "worker_b"
main = "./src/workerB.js"
```
+
+
```js
import { WorkerEntrypoint } from "cloudflare:workers";
export default class extends WorkerEntrypoint {
async fetch() { return new Response("Hello from Worker B"); }
-
- add(a, b) { return a + b; }
+
+ add(a, b) { return a + b; }
}
```
Worker A can declare a [binding](/workers/runtime-apis/bindings) to Worker B:
+
+
+
+
```toml
name = "worker_a"
main = "./src/workerA.js"
@@ -30,6 +40,8 @@ services = [
]
```
+
+
Making it possible for Worker A to call the `add()` method from Worker B:
```js
diff --git a/src/content/partials/workers/service-binding-rpc-functions-example.mdx b/src/content/partials/workers/service-binding-rpc-functions-example.mdx
index fd40926aa4d66f8..2a62bdd4f39fbd2 100644
--- a/src/content/partials/workers/service-binding-rpc-functions-example.mdx
+++ b/src/content/partials/workers/service-binding-rpc-functions-example.mdx
@@ -5,11 +5,17 @@
Consider the following two Workers, connected via a [Service Binding](/workers/runtime-apis/bindings/service-bindings/rpc). The counter service provides the RPC method `newCounter()`, which returns a function:
+import { WranglerConfig } from "~/components";
+
+
+
```toml
name = "counter-service"
main = "./src/counterService.js"
```
+
+
```js
import { WorkerEntrypoint } from "cloudflare:workers";
@@ -28,6 +34,10 @@ export default class extends WorkerEntrypoint {
This function can then be called by the client Worker:
+
+
+
+
```toml
name = "client_worker"
main = "./src/clientWorker.js"
@@ -36,6 +46,8 @@ services = [
]
```
+
+
```js
export default {
async fetch(request, env) {
@@ -51,7 +63,7 @@ export default {
:::note
-Refer to [Explicit Resource Management](/workers/runtime-apis/rpc/lifecycle) to learn more about the `using` declaration shown in the example above.
+Refer to [Explicit Resource Management](/workers/runtime-apis/rpc/lifecycle) to learn more about the `using` declaration shown in the example above.
:::
How is this possible? The system is not serializing the function itself. When the function returned by `CounterService` is called, it runs within `CounterService` — even if it is called by another Worker.
diff --git a/src/content/partials/workers/wrangler-tail-warning.mdx b/src/content/partials/workers/wrangler-tail-warning.mdx
index c5fc508b7c4d8e4..a7527178fe7d0d2 100644
--- a/src/content/partials/workers/wrangler-tail-warning.mdx
+++ b/src/content/partials/workers/wrangler-tail-warning.mdx
@@ -8,9 +8,15 @@
When updating a Worker with Wrangler the [Tail Consumer](/workers/observability/logs/tail-workers) config will be removed. Please add the tail\_consumer config to the top level of your `wrangler.toml`.
+import { WranglerConfig } from "~/components";
+
+
+
```toml
tail_consumers = [{service = ""}]
```
+
+
:::
diff --git a/templates/tutorial-template.mdx b/templates/tutorial-template.mdx
index bc72f52fb2ccdec..226978593a58064 100644
--- a/templates/tutorial-template.mdx
+++ b/templates/tutorial-template.mdx
@@ -76,6 +76,10 @@ export default {
(Wrangler toml file example.)
+import { WranglerConfig } from "~/components";
+
+
+
```toml title="wrangler.toml"
#:schema node_modules/wrangler/config-schema.json
name = ""
@@ -87,6 +91,8 @@ compatibility_flags = ["nodejs_compat"]
binding = "AI"
```
+
+
(Aside examples. For more details read our [style guide documentation on Notes/tips/warnings](/style-guide/documentation-content-strategy/component-attributes/notes-tips-warnings/#recommendations).)
:::note[Aside example]
diff --git a/worker-configuration.d.ts b/worker-configuration.d.ts
index f6f800622d88aaf..78c2754b48a559b 100644
--- a/worker-configuration.d.ts
+++ b/worker-configuration.d.ts
@@ -1,5 +1,4 @@
-// Generated by Wrangler on Tue Sep 17 2024 00:57:27 GMT-0400 (Eastern Daylight Time)
-// by running `wrangler types -c wrangler-workers.toml --experimental-include-runtime`
+// Generated by Wrangler by running `wrangler types -c wrangler-workers.toml --experimental-include-runtime`
interface Env {
API_DOCS_KV: KVNamespace;
@@ -8,4 +7,4 @@ interface Env {
declare module "*/_redirects" {
const value: string;
export default value;
-}
+}
\ No newline at end of file