Wrangler config updates (#18313)

Author: penalosa

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 `<WranglerConfig>` component, which ensure it's rendered as both JSON and TOML e.g.
+
+````
+
+import { WranglerConfig } from "~/components";
+
+<WranglerConfig>
+
+```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 = "<MY_NAMESPACE>", id = "<KV_ID>" }
+]
+
+[env.staging]
+name = "my-worker-staging"
+route = { pattern = "staging.example.org/*", zone_name = "example.org" }
+
+kv_namespaces = [
+  { binding = "<MY_NAMESPACE>", id = "<STAGING_KV_ID>" }
+]
+```
+
+</WranglerConfig>
+
+````
 
 ## 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
 
 <img width="870" alt="Screenshot 2024-02-20 at 14 29 22" src="https://github.com/cloudflare/cloudflare-docs/assets/28503158/56aa8016-b3b6-4d64-8213-b1a26f16534a">

package-lock.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",

package.json

@@ -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));
+}
+---
+
+<Tabs syncKey="wranglerConfig">
+	<TabItem label="wrangler.toml" icon="setting">
+		<Code lang="toml" code={toml} />
+	</TabItem>
+	<TabItem label="wrangler.json" icon="seti:json">
+		<Code lang="jsonc" code={json} />
+	</TabItem>
+</Tabs>

src/components/WranglerConfig.astro

@@ -53,6 +53,7 @@ export { default as TroubleshootingList } from "./TroubleshootingList.astro";
 export { default as TunnelCalculator } from "./TunnelCalculator.astro";
 export { default as Type } from "./Type.astro";
 export { default as TypeScriptExample } from "./TypeScriptExample.astro";
+export { default as WranglerConfig } from "./WranglerConfig.astro";
 export { default as WorkersArchitectureDiagram } from "./WorkersArchitectureDiagram.astro";
 export { default as WorkersIsolateDiagram } from "./WorkersIsolateDiagram.astro";
 export { default as WorkerStarter } from "./WorkerStarter.astro";

src/components/index.ts

@@ -49,11 +49,17 @@ You must create an AI binding for your Worker to connect to Workers AI. Bindings
 
 To bind Workers AI to your Worker, add the following to the end of your `wrangler.toml` file:
 
+import { WranglerConfig } from "~/components";
+
+<WranglerConfig>
+
 ```toml title="wrangler.toml"
 [ai]
 binding = "AI"
 ```
 
+</WranglerConfig>
+
 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/).
 
 You will need to have your `gateway id` for the next step. You can learn [how to create an AI Gateway in this tutorial](/ai-gateway/get-started/).

src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx

@@ -15,12 +15,18 @@ import { DirectoryListing } from "~/components"
 
 Add the following to your `wrangler.toml` file to create a [binding](/workers/runtime-apis/bindings/) to a Workers Analytics Engine dataset. A dataset is like a table in SQL: the rows and columns should have consistent meaning.
 
+import { WranglerConfig } from "~/components";
+
+<WranglerConfig>
+
 ```toml
 [[analytics_engine_datasets]]
 binding = "<BINDING_NAME>"
 dataset = "<DATASET_NAME>"
 ```
 
+</WranglerConfig>
+
 ## 2. Write data points from your Worker
 
 You can write data points to your Worker by calling the `writeDataPoint()` method that is exposed on the binding that you just created.
@@ -38,7 +44,7 @@ async fetch(request, env) {
 
 :::note
 
-You do not need to await `writeDataPoint()` — it will return immediately, and the Workers runtime handles writing your data in the background. 
+You do not need to await `writeDataPoint()` — it will return immediately, and the Workers runtime handles writing your data in the background.
 :::
 
 A data point is a structured event that consists of:
@@ -81,7 +87,7 @@ LIMIT 10
 
 :::note
 
-We are using a custom averaging function to take [sampling](/analytics/analytics-engine/sql-api/#sampling) into account. 
+We are using a custom averaging function to take [sampling](/analytics/analytics-engine/sql-api/#sampling) into account.
 :::
 
 You can run this query by making an HTTP request to the SQL API:
@@ -117,6 +123,6 @@ Refer to [Querying Workers Analytics Engine from Grafana](/analytics/analytics-e
 
 ## Further reading
 
-<DirectoryListing 
+<DirectoryListing
 folder="analytics/analytics-engine"
 />

src/content/docs/analytics/analytics-engine/get-started.mdx

@@ -48,11 +48,17 @@ First the environment variables are set up with the account ID and API token.
 
 The account ID is set in `wrangler.toml`:
 
+import { WranglerConfig } from "~/components";
+
+<WranglerConfig>
+
 ```toml
 [vars]
 ACCOUNT_ID = "<account_id>"
 ```
 
+</WranglerConfig>
+
 The API_TOKEN can be set as a secret, using the wrangler command line tool, by running the following and entering your token string:
 
 ```sh

src/content/docs/analytics/analytics-engine/worker-querying.mdx

@@ -75,12 +75,16 @@ Configure your `browser-worker` project's [`wrangler.toml`](/workers/wrangler/co
 
 Update your `wrangler.toml` configuration file with the Browser Rendering API binding, the R2 bucket you created and a Durable Object:
 
+import { WranglerConfig } from "~/components";
+
+<WranglerConfig>
+
 ```toml
 name = "rendering-api-demo"
 main = "src/index.js"
 compatibility_date = "2023-09-04"
 compatibility_flags = [ "nodejs_compat"]
-account_id = <ACCOUNT_ID>
+account_id = "<ACCOUNT_ID>"
 
 
 # Browser Rendering API binding
@@ -103,6 +107,8 @@ new_classes = ["Browser"] # Array of new classes
 
 ```
 
+</WranglerConfig>
+
 ## 6. Code
 
 The code below uses Durable Object to instantiate a browser using Puppeteer. It then opens a series of web pages with different resolutions, takes a screenshot of each, and uploads it to R2.

src/content/docs/browser-rendering/get-started/browser-rendering-with-DO.mdx

@@ -62,6 +62,10 @@ Configure your `browser-worker` project's [`wrangler.toml`](/workers/wrangler/co
 
 Update your `wrangler.toml` configuration file with the Browser Rendering API binding and the KV namespaces you created:
 
+import { WranglerConfig } from "~/components";
+
+<WranglerConfig>
+
 ```toml
 name = "browser-worker"
 main = "src/index.js"
@@ -74,6 +78,8 @@ kv_namespaces = [
 ]
 ```
 
+</WranglerConfig>
+
 ## 5. Code
 
 <Tabs> <TabItem label="JavaScript" icon="seti:javascript">