From 49c069b7b5802ca8e43d0912ba722a8c49b7daf0 Mon Sep 17 00:00:00 2001 From: korinne Date: Thu, 5 Jun 2025 13:05:29 -0700 Subject: [PATCH 01/12] adds draft docs for connecting to remote resources during local dev (hybrid dev) --- .../docs/workers/local-development/index.mdx | 301 ++++++++++++++++-- .../workers/local-development/local-data.mdx | 4 +- .../workers/local-development/remote-data.mdx | 53 --- .../local-development/wrangler-vs-vite.mdx | 42 +++ 4 files changed, 319 insertions(+), 81 deletions(-) delete mode 100644 src/content/docs/workers/local-development/remote-data.mdx create mode 100644 src/content/docs/workers/local-development/wrangler-vs-vite.mdx diff --git a/src/content/docs/workers/local-development/index.mdx b/src/content/docs/workers/local-development/index.mdx index c354b6110cb114..eaf59510ce13a9 100644 --- a/src/content/docs/workers/local-development/index.mdx +++ b/src/content/docs/workers/local-development/index.mdx @@ -7,45 +7,294 @@ head: [] description: Develop your Workers locally. --- -import { Details, LinkCard, Render, PackageManagers } from "~/components"; +import { + Details, + LinkCard, + Render, + PackageManagers, + WranglerConfig, + Aside, +} from "~/components"; -When building projects on Cloudflare Workers, you have two options for local development: +Local development allows you to build, run, and test your Worker code on your own machine before deploying it to Cloudflare's network. This is made possible through [Miniflare](/workers/testing/miniflare/), a simulator that executes your Worker code using the same runtime used in production, [`workerd`](https://github.com/cloudflare/workerd). By default, your Worker's bindings connect to locally simulated resources, but can be configured to interact with the real, production resource. -- [**Wrangler**](/workers/wrangler/), using the built-in [`wrangler dev`](/workers/wrangler/commands/#dev) command. -- [Vite](https://vite.dev/), using the [**Cloudflare Vite plugin**](/workers/vite-plugin/). +## Start a development server -Both Wrangler and the Vite plugin use [Miniflare](/workers/testing/miniflare/) to provide an accurate **local** simulation of the Cloudflare Workers runtime, ([`workerd`](https://github.com/cloudflare/workerd)). If you need to [develop with **remote resources**](/workers/local-development/remote-data/), Wrangler is the only option, and provides remote development via the `wrangler dev --remote` command. +You can start a local development server using: -## Choosing between Wrangler or Vite +1. Our official CLI [**Wrangler**](/workers/wrangler/), using the built-in [`wrangler dev`](/workers/wrangler/commands/#dev) command. -Deciding between Wrangler and the Cloudflare Vite plugin depends on your project's focus and development workflow. Here are some quick guidelines to help you choose: + -### When to use Wrangler +2. [**Vite**](https://vite.dev/), using the [**Cloudflare Vite plugin**](/workers/vite-plugin/). -- **Backend & Workers-focused:** - If you're primarily building APIs, serverless functions, or background tasks, use Wrangler. + -- **Remote development:** - If your project needs the ability to develop and test using production resources and data on Cloudflare's network, use Wrangler's `--remote` flag. +Both Wrangler and the Cloudflare Vite plugin are clients to Miniflare, and fully supported by Cloudflare. For guidance on choosing when to use Wrangler versus Vite, see our guide [Choosing between Wrangler & Vite](/workers/local-development/wrangler-vs-vite/). -- **Simple frontends:** - If you have minimal frontend requirements and don’t need hot reloading or advanced bundling, Wrangler may be sufficient. +- [Get started with Wrangler](/workers/wrangler/install-and-update/) +- [Get started with the Cloudflare Vite plugin](/workers/vite-plugin/get-started/) -### When to use the Cloudflare Vite Plugin +### Default Behavior (Fully local) -Use the [Vite plugin](/workers/vite-plugin/) for: +By default, running `wrangler dev` / `vite dev` (when using the [Vite plugin](/workers/vite-plugin/get-started/)) means that: -- **Frontend-centric development:** - If you already use Vite with modern frontend frameworks like React, Vue, Svelte, or Solid, the Vite plugin integrates into your development workflow. +- Your Worker code runs on your local machine. +- All resources your Worker is bound to in your [Wrangler configuration](/workers/wrangler/configuration/) are simulated locally. -- **React Router v7:** - If you are using [React Router v7](https://reactrouter.com/) (the successor to Remix), it is officially supported by the Vite plugin as a full-stack SSR framework. +### Bindings during local development -- **Rapid iteration (HMR):** - If you need near-instant updates in the browser, the Vite plugin provides [Hot Module Replacement (HMR)](https://vite.dev/guide/features.html#hot-module-replacement) during local development. +[Bindings](/workers/runtime-apis/bindings/) are interfaces that allow your Worker to interact with various Cloudflare resources (like [KV namespaces](/kv), [R2 buckets](/r2), [D1 databases](/d1), [Queues](/queues/), [Durable Objects](/durable-objects/), etc). In your Worker code, these are accessed via the `env` object (such as `env.MY_KV`). -- **Advanced optimizations:** - If you require more advanced optimizations (code splitting, efficient bundling, CSS handling, build time transformations, etc.), Vite is a strong fit. +During local development, your Worker code interacts with these bindings using the exact same API calls (such as `env.MY_KV.put()`) as it would in a deployed environment. Miniflare intercepts these calls and directs them to the locally simulated resource. These local resources are initially empty, but you can populate them with data, as documented in [Adding local data](/workers/local-development/local-data/). -- **Greater flexibility:** - Due to Vite's advanced configuration options and large ecosystem of plugins, there is more flexibility to customize your development experience and build output. +- By default, bindings connect to **local resource simulations** (except for [AI bindings](/workers-ai/configuration/bindings/), as AI models always run remotely). +- You can override this default behavior and **connect to the remote resource**, on a per-binding basis. This lets you connect to real, production resources while still running your Worker code locally. + +## Connect to remote resources (Hybrid) + +There are times when you might want to connect to the real, remote resource during local development _instead_ of the locally simulated resource. You can configure this on a per-binding basis, by setting `remote: true` in the binding definition. + +**For example:** + + + +```jsonc title="wrangler.jsonc" +{ + "name": "my-worker", + "compatibility_date": "2025-06-01", + + "browser": { + "binding": "MY_BROWSER", + "remote": true, + }, + + "queues": { + "producers": [ + { + "queue": "queues-web-crawler", + "binding": "queues_web_crawler", + "remote": false, // Default value, but here for illustration + }, + ], + "consumers": [ + { + "queue": "queues-web-crawler", + "max_batch_size": 5, + "max_batch_timeout": 30, + "max_retries": 3, + "dead_letter_queue": "web-crawler-dlq", + "remote": false, // Default value, but here for illustration + }, + ], + }, + + "r2_buckets": [ + { + "bucket_name": "screenshots-bucket", + "binding": "screenshots_bucket", + "preview_bucket_name": "preview-screenshots-bucket", + "remote": true, + }, + ], +} +``` + + + +In the above example, you’re able to more realistically test out and trust that any [Browser Rendering](/browser-rendering/) interactions work as intended, as well as validate the end results of the screenshots in R2 – while leaving room to rapidly iterate on the actual logic within your Worker and queues. + + + +### How it works + +When you run you local dev command and a binding definition includes `remote: true`, the following takes place: + +- Your Worker's code continues to run on your machine within `workerd`, managed by Miniflare (whether initiated by Wrangler or Vite). +- For all bindings marked with `remote: true`, Miniflare routes its operations (such as `env.MY_KV.put()`) to the deployed resource. This connection is facilitated through a secure proxy mechanism provisioned on Cloudflare's network. +- All other bindings not explicitly configured with `remote: true` continue to use their default local simulations. +- Your Worker code remains unchanged, regardless of whether the bindings is fully local or connected remotely. + +### Targeting Preview vs. Production resources + +To protect production data, you can create and specify preview resources in your [Wrangler configuration](/workers/wrangler/configuration/), such as: + +- [Preview namespaces for KV stores](/workers/wrangler/configuration/#kv-namespaces):`preview_id`. +- [Preview buckets for R2 storage](/workers/wrangler/configuration/#r2-buckets): `preview_bucket_name`. +- [Preview database IDs for D1](/workers/wrangler/configuration/#d1-databases): `preview_database_id` + +If preview configuration is present for a binding, setting `remote: true` will make your local session connect to that designated remote preview resource. +If no preview configuration is specified, `remote: true` will connect to the main remote production resource. + +**For example:** + + + +```jsonc title="wrangler.jsonc" +{ + "name": "my-worker", + "compatibility_date": "2025-06-01", + + "r2_buckets": [ + { + "bucket_name": "screenshots-bucket", + "binding": "screenshots_bucket", + "preview_bucket_name": "preview-screenshots-bucket", + "remote": true, + }, + ], +} +``` + + + +Running your local dev command (`wrangler dev` / `vite dev`) with the above configuration means that: + +- Your Worker code runs locally +- All calls made to `env.screenshots_bucket` will use the `preview-screenshots-bucket` resource, rather than the production `screenshots-bucket`. + +### Recommended remote bindings + +We recommend configuring specific bindings to connect to their remote counterparts. These services often rely on Cloudflare's network infrastructure or have complex backends that are not fully simulated locally. + +The following bindings are recommended to have `remote: true` in your Wrangler configuration: + +- [**Browser Rendering**](/workers/wrangler/configuration/#browser-rendering): To interact with a real headless browser for rendering. + +- [**Workers AI**](/workers/wrangler/configuration/#workers-ai): To utilize actual AI models deployed on Cloudflare's network for inference. + +- [**Vectorize**](/workers/wrangler/configuration/#vectorize-indexes): To connect to your production Vectorize indexes for accurate vector search and similarity operations. + +- **Service bindings to [mTLS-enabled services](/workers/wrangler/configuration/#mtls-certificates)**: If you have a service binding that points to a deployed Worker or service that requires mTLS authentication from its clients, setting `remote: true` for that service binding is recommended for realistic end-to-end testing. Your Worker would then use an `mtls_certificates` binding to make the call. + +#### Behavior and configuration: + +- If `remote: true` is not specified for Browser Rendering, Vectorize, or for a service binding that is intended to call an mTLS-protected remote service, Cloudflare will issue a warning. This prompts you to consider enabling it for a more production-like testing experience. +- For Workers AI, if the `ai.remote` property is set to `false`, Cloudflare will produce an error. If the property is omitted, Cloudflare will connect to the remote resource and issue a warning to add the property to configuration. + + +```jsonc title="wrangler.jsonc" +{ + "name": "my-worker", + "compatibility_date": "2025-06-01", + // ... other configurations ... + "browser": { + "binding": "MY_BROWSER", + "remote": true // Recommended + }, + "vectorize": [ + { + "binding": "MY_VECTORIZE_INDEX", + "index_name": "my-prod-index", + "remote": true // Recommended + } + ], + "services": [ + { + "binding": "API_SERVICE_REQUIRING_MTLS", // A service this worker calls + "service": "deployed-api-worker-expecting-mtls", // This target service expects mTLS + "remote": true // Recommended + } + ], + "ai": { + "binding": "AI", // Access as env.AI + "remote": true // Required; setting to false or omitting will error + }, + "mtls_certificates": [ // Defines how this worker can present a client certificate + { + "binding": "MY_CLIENT_CERT_FETCHER", // Access as env.MY_CLIENT_CERT_FETCHER + "certificate_id": "" + // Note: 'remote: true' is NOT applicable here. This binding provides a + // an object that has a `.fetch()` method. + } + ] + // Note: For other services like KV, R2, D1, Queues, 'remote: true' is optional +} +``` + + +### Limitations - Unsupported remote bindings + +While the hybrid approach allows many bindings to connect to remote resources, certain bindings are not supported for remote connections during local development (`remote: true`). These will always use local simulations or local values. + +If `remote: true` is specified in Wrangler configuration for any of the following unsupported binding types, Cloudflare will issue an error. + +- [**Durable Objects**](/workers/wrangler/configuration/#durable-objects): Durable Objects have synchronous operational aspects in their API. The current hybrid development proxy mechanism primarily supports asynchronous operations. Enabling remote connections for Durable Objects may be supported in the future, but currently will always run locally. + +- [**Environment Variables (`vars`)**](/workers/wrangler/configuration/#environment-variables): Environment variables are intended to be distinct between local development and deployed environments (`production`, `preview`). They are easily configurable locally (such as in a `.dev.vars` file or directly in Wrangler configuration. + +- [**Secrets**](/workers/wrangler/configuration/#secrets): Like environment variables, secrets are expected to have different values in local development versus deployed environments for security reasons. Use `.dev.vars` for local secret management. + +- **[Assets (Static Assets)](//workers/wrangler/configuration/#assets)**: Static assets are always served from your local disk during development for speed and direct feedback on changes. + +- [**Version Metadata**](/workers/runtime-apis/bindings/version-metadata/): Since your Worker code is running locally, version metadata (like commit hash, version tags) associated with a specific deployed version is not applicable or accurate. + +- [**Analytics Engine**](/analytics/analytics-engine/): Local development sessions typically don't contribute data directly to production Analytics Engine. + +- [**Hyperdrive**](/workers/wrangler/configuration/#hyperdrive): This is being actively worked on, but is currently unsupported. +- [**Rate Limiting**](/workers/runtime-apis/bindings/rate-limit/#configuration): Local development sessions typically should not share or affect rate limits of your deployed Workers. Rate limiting logic should be tested against local simulations. + + + +### Important Considerations + +- **Data modification**: Operations (writes, deletes, updates) on bindings connected remotely will affect your actual data in the targeted Cloudflare resource (be it preview or production). + +- **Billing**: Interactions with remote Cloudflare services through these connections will incur standard operational costs for those services (such as KV operations, R2 storage/operations, AI requests, D1 usage). + +- **Network latency**: Expect network latency for operations on these remotely connected bindings, as they involve communication over the internet. + +- **Environment Variables & Secrets**: Standard environment variables (from [vars]) and Secrets always use their locally defined values during local development. The `remote: true` flag does not apply to them. + +### API + +TO-DO + +## Remote development + +Separate from Miniflare-powered local development, Wrangler also offers a fully remote development mode via [`wrangler dev --remote`](/workers/wrangler/commands/#dev). Remote development is [**not** supported in the Vite plugin](/workers/local-development/wrangler-vs-vite/). + + + +### How It Works + +The `wrangler dev --remote` command creates a temporary preview deployment on Cloudflare's infrastructure. + +When you run `wrangler dev --remote`: + +- All of your code is uploaded to a temporary preview environment on Cloudflare's infrastructure. +- Changes to your code are automatically uploaded as you save. +- All requests and execution happen on Cloudflare's global network. +- The preview automatically terminates when you exit the command. + +### When to use Remote development + +- For most development tasks, the most efficient and productive experience will be local development along with [connections to remote resources](/workers/local-development/#connect-to-remote-resources-hybrid). +- You may want to use `wrangler dev --remote` for testing features or behaviors that are highly specific to Cloudflare's network and cannot be adequately simulated locally or tested via hybrid connections. + +### Considerations + +- Iteration is significantly slower than local development due to the upload/deployment step for each change. + +### Isolating from Production + +To protect production data, you can specify preview resources in your [Wrangler configuration](/workers/wrangler/configuration/), such as: + +- [Preview namespaces for KV stores](/workers/wrangler/configuration/#kv-namespaces):`preview_id`. + - This option is **required** when using `wrangler dev --remote`. +- [Preview buckets for R2 storage](/workers/wrangler/configuration/#r2-buckets): `preview_bucket_name`. +- [Preview database IDs for D1](/workers/wrangler/configuration/#d1-databases): `preview_database_id` + +This separation ensures your development activities don't impact production data while still providing a realistic testing environment. + +### Limitations + +- When you run a remote development session using the `--remote` flag, a limit of 50 [routes](/workers/configuration/routing/routes/) per zone is enforced. Learn more in[ Workers platform limits](/workers/platform/limits/#number-of-routes-per-zone-when-using-wrangler-dev---remote). diff --git a/src/content/docs/workers/local-development/local-data.mdx b/src/content/docs/workers/local-development/local-data.mdx index 5a3b20a8022280..b2f00f8f26edb3 100644 --- a/src/content/docs/workers/local-development/local-data.mdx +++ b/src/content/docs/workers/local-development/local-data.mdx @@ -1,10 +1,10 @@ --- pcx_content_type: navigation -title: Local data +title: Adding local data sidebar: order: 2 head: [] -description: Working with data during local development +description: Populating local resources with data --- import { diff --git a/src/content/docs/workers/local-development/remote-data.mdx b/src/content/docs/workers/local-development/remote-data.mdx deleted file mode 100644 index db44b976af3b81..00000000000000 --- a/src/content/docs/workers/local-development/remote-data.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -pcx_content_type: navigation -title: Remote data -sidebar: - order: 3 -head: [] -description: Working with data during remote development ---- - -import { - Details, - LinkCard, - Render, - PackageManagers, - FileTree, -} from "~/components"; - -When developing Workers applications, you can use Wrangler's remote development mode (via [`wrangler dev --remote`](/workers/wrangler/commands/#dev)) to test your code on Cloudflare's global network before -deploying to production. Remote development is [**not** supported in the Vite plugin](/workers/local-development/#choosing-between-wrangler-or-vite). - - - -### How It Works - -The `wrangler dev --remote` command creates a temporary preview deployment on Cloudflare's infrastructure, allowing you to test your Worker in an environment that closely mirrors production. - -When you run `wrangler dev --remote`: - -- Your code is uploaded to a temporary preview environment on Cloudflare's infrastructure. -- Changes to your code are automatically uploaded as you save. -- All requests and execution happen on Cloudflare's global network -- The preview automatically terminates when you exit the command - -## When to Use Remote Development - -- You need to develop using [bindings that don't work locally](/workers/local-development/bindings-per-env/) (such as [Browser Rendering](/browser-rendering/)). -- You need to verify behavior specifically on Cloudflare's infrastructure. -- You want to work with preview resources that mirror production. - -## Isolating from Production - -To protect production data, you can specify preview resources in your [Wrangler configuration](/workers/wrangler/configuration/), such as: - -- [Preview namespaces for KV stores](/workers/wrangler/configuration/#kv-namespaces):`preview_id`. - - This option is **required** when using `wrangler dev --remote`. -- [Preview buckets for R2 storage](/workers/wrangler/configuration/#r2-buckets): `preview_bucket_name`. -- [Preview database IDs for D1](/workers/wrangler/configuration/#d1-databases): `preview_database_id` - -This separation ensures your development activities don't impact production data while still providing a realistic testing environment. - -## Limitations - -- When you run a remote development session using the `--remote` flag, a limit of 50 [routes](/workers/configuration/routing/routes/) per zone is enforced. Learn more in[ Workers platform limits](/workers/platform/limits/#number-of-routes-per-zone-when-using-wrangler-dev---remote). diff --git a/src/content/docs/workers/local-development/wrangler-vs-vite.mdx b/src/content/docs/workers/local-development/wrangler-vs-vite.mdx new file mode 100644 index 00000000000000..ea046fe2586a98 --- /dev/null +++ b/src/content/docs/workers/local-development/wrangler-vs-vite.mdx @@ -0,0 +1,42 @@ +--- +pcx_content_type: navigation +title: Choosing between Wrangler & Vite +sidebar: + order: 4 +head: [] +description: Choosing between Wrangler and Vite for local development +--- + +# When to use Wrangler vs Vite + +Deciding between Wrangler and the Cloudflare Vite plugin depends on your project's focus and development workflow. Here are some quick guidelines to help you choose: + +## When to use Wrangler + +- **Backend & Workers-focused:** + If you're primarily building APIs, serverless functions, or background tasks, use Wrangler. + +- **Remote development:** + If your project needs the ability to develop and test using production resources and data on Cloudflare's network, use Wrangler's `--remote` flag. + +- **Simple frontends:** + If you have minimal frontend requirements and don’t need hot reloading or advanced bundling, Wrangler may be sufficient. + +## When to use the Cloudflare Vite Plugin + +Use the [Vite plugin](/workers/vite-plugin/) for: + +- **Frontend-centric development:** + If you already use Vite with modern frontend frameworks like React, Vue, Svelte, or Solid, the Vite plugin integrates into your development workflow. + +- **React Router v7:** + If you are using [React Router v7](https://reactrouter.com/) (the successor to Remix), it is officially supported by the Vite plugin as a full-stack SSR framework. + +- **Rapid iteration (HMR):** + If you need near-instant updates in the browser, the Vite plugin provides [Hot Module Replacement (HMR)](https://vite.dev/guide/features.html#hot-module-replacement) during local development. + +- **Advanced optimizations:** + If you require more advanced optimizations (code splitting, efficient bundling, CSS handling, build time transformations, etc.), Vite is a strong fit. + +- **Greater flexibility:** + Due to Vite's advanced configuration options and large ecosystem of plugins, there is more flexibility to customize your development experience and build output. From 0da08bfcd20a47a249a5dffb8fecc1af370c5151 Mon Sep 17 00:00:00 2001 From: korinne <40270578+korinne@users.noreply.github.com> Date: Tue, 10 Jun 2025 11:47:11 -0700 Subject: [PATCH 02/12] Update src/content/docs/workers/local-development/index.mdx Co-authored-by: Pete Bacon Darwin --- src/content/docs/workers/local-development/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/local-development/index.mdx b/src/content/docs/workers/local-development/index.mdx index eaf59510ce13a9..04771a5bb6e1b1 100644 --- a/src/content/docs/workers/local-development/index.mdx +++ b/src/content/docs/workers/local-development/index.mdx @@ -16,7 +16,7 @@ import { Aside, } from "~/components"; -Local development allows you to build, run, and test your Worker code on your own machine before deploying it to Cloudflare's network. This is made possible through [Miniflare](/workers/testing/miniflare/), a simulator that executes your Worker code using the same runtime used in production, [`workerd`](https://github.com/cloudflare/workerd). By default, your Worker's bindings connect to locally simulated resources, but can be configured to interact with the real, production resource. +Local development allows you to build, run, and test your Worker code on your own machine before deploying it to Cloudflare's network. This is made possible through [Miniflare](/workers/testing/miniflare/), a simulator that executes your Worker code using the same runtime used in production, [`workerd`](https://github.com/cloudflare/workerd). By default, your Worker's bindings connect to locally simulated resources, but can be configured to interact with real, production resources. ## Start a development server From 475059f8f52db184cfec076095a861ceac96af99 Mon Sep 17 00:00:00 2001 From: korinne <40270578+korinne@users.noreply.github.com> Date: Tue, 10 Jun 2025 11:47:47 -0700 Subject: [PATCH 03/12] Update src/content/docs/workers/local-development/index.mdx Co-authored-by: Pete Bacon Darwin --- src/content/docs/workers/local-development/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/local-development/index.mdx b/src/content/docs/workers/local-development/index.mdx index 04771a5bb6e1b1..79048b4e7e8f51 100644 --- a/src/content/docs/workers/local-development/index.mdx +++ b/src/content/docs/workers/local-development/index.mdx @@ -30,7 +30,7 @@ You can start a local development server using: -Both Wrangler and the Cloudflare Vite plugin are clients to Miniflare, and fully supported by Cloudflare. For guidance on choosing when to use Wrangler versus Vite, see our guide [Choosing between Wrangler & Vite](/workers/local-development/wrangler-vs-vite/). +Both Wrangler and the Cloudflare Vite plugin both use Miniflare under the hood, and are developed and maintained by the Cloudflare team. For guidance on choosing when to use Wrangler versus Vite, see our guide [Choosing between Wrangr & Vite](/workers/local-development/wrangler-vs-vite/). - [Get started with Wrangler](/workers/wrangler/install-and-update/) - [Get started with the Cloudflare Vite plugin](/workers/vite-plugin/get-started/) From 3f9ab866284562ad5fafd23417efff637817b7a3 Mon Sep 17 00:00:00 2001 From: korinne Date: Thu, 12 Jun 2025 00:58:04 -0700 Subject: [PATCH 04/12] updates overview pages, bindings-per-env for new hybrid dev --- .../bindings-per-env.mdx | 4 +- .../environment-variables.mdx | 0 .../workers/development-testing/index.mdx | 361 ++++++++++++++++++ .../local-data.mdx | 2 +- .../workers/development-testing/testing.mdx | 7 + .../development-testing/vite-plugin.mdx | 7 + .../wrangler-vs-vite.mdx | 2 +- .../docs/workers/local-development/index.mdx | 300 --------------- .../partials/workers/bindings_per_env.mdx | 60 ++- 9 files changed, 408 insertions(+), 335 deletions(-) rename src/content/docs/workers/{local-development => development-testing}/bindings-per-env.mdx (55%) rename src/content/docs/workers/{local-development => development-testing}/environment-variables.mdx (100%) create mode 100644 src/content/docs/workers/development-testing/index.mdx rename src/content/docs/workers/{local-development => development-testing}/local-data.mdx (99%) create mode 100644 src/content/docs/workers/development-testing/testing.mdx create mode 100644 src/content/docs/workers/development-testing/vite-plugin.mdx rename src/content/docs/workers/{local-development => development-testing}/wrangler-vs-vite.mdx (99%) delete mode 100644 src/content/docs/workers/local-development/index.mdx diff --git a/src/content/docs/workers/local-development/bindings-per-env.mdx b/src/content/docs/workers/development-testing/bindings-per-env.mdx similarity index 55% rename from src/content/docs/workers/local-development/bindings-per-env.mdx rename to src/content/docs/workers/development-testing/bindings-per-env.mdx index 62a4c347df5add..ce516c39554aa6 100644 --- a/src/content/docs/workers/local-development/bindings-per-env.mdx +++ b/src/content/docs/workers/development-testing/bindings-per-env.mdx @@ -1,10 +1,10 @@ --- pcx_content_type: navigation -title: Supported bindings in local and remote dev +title: Supported bindings per development mode sidebar: order: 4 head: [] -description: Supported bindings in local and remote development +description: Supported bindings per development mode --- import { Render } from "~/components"; diff --git a/src/content/docs/workers/local-development/environment-variables.mdx b/src/content/docs/workers/development-testing/environment-variables.mdx similarity index 100% rename from src/content/docs/workers/local-development/environment-variables.mdx rename to src/content/docs/workers/development-testing/environment-variables.mdx diff --git a/src/content/docs/workers/development-testing/index.mdx b/src/content/docs/workers/development-testing/index.mdx new file mode 100644 index 00000000000000..ec3a31428522a2 --- /dev/null +++ b/src/content/docs/workers/development-testing/index.mdx @@ -0,0 +1,361 @@ +--- +pcx_content_type: navigation +title: Development & testing +sidebar: + order: 6 +head: [] +description: Develop and test your Workers locally or with hybrid approaches. +--- + +import { + Details, + LinkCard, + Render, + PackageManagers, + WranglerConfig, + Aside, + InlineBadge, + CardGrid, + Card, +} from "~/components"; + +Cloudflare Workers offers three distinct development modes to build, run, and test your Worker code before deploying to production. Choose from [fully **local development**](/workers/development-testing/#local-development) with simulated resources, [**hybrid development**](/workers/development-testing/#hybrid-development) that combines local execution with remote resource connections, or [legacy **remote development**](/workers/development-testing/#remote-development-legacy) that runs entirely on Cloudflare's infrastructure. + +## Core concepts + +### Worker execution vs Bindings + +When developing Workers, it's important to understand two distinct concepts: + +- **Worker execution**: Where your Worker code actually runs (on your local machine vs on Cloudflare's infrastructure). + +- **Bindings**: How your Worker interacts with Cloudflare resources (like [KV namespaces](/kv), [R2 buckets](/r2), [D1 databases](/d1), [Queues](/queues/), [Durable Objects](/durable-objects/), etc). In your Worker code, these are accessed via the `env` object (such as `env.MY_KV`). + +While these are independent concepts, **where your Worker** runs and **how bindings connect** determines which [development mode](/workers/development-testing/#development-modes) you're using. + +### Development Modes + +Based on where your Worker runs and how bindings connect, there are three development modes: + + + **Worker execution**: Runs locally on your machine via `wrangler dev` / [`vite dev`](/workers/vite-plugin/get-started/). + + **Bindings**: Connect to local resource simulations by default. + + [Learn more.](/workers/development-testing/#local-development) + + + + **Worker execution**: Runs locally on your machine, via the experimental `wrangler dev --x-hybrid-dev` command. + + **Bindings**: Can connect to local resource simulations (default) or be configured to connect to the deployed, remote resource. + + [Learn more.](/workers/development-testing/#hybrid-development) + + + + **Worker execution**: Runs on Cloudflare's infrastructure via `wrangler dev --remote`. + + **Bindings**: Always connect to remote resources. + + [Learn more.](/workers/development-testing/#remote-development-legacy) + + +## Local development + +Local development allows you to build, run, and test your Worker code on your own machine before deploying it to Cloudflare's network. This is made possible through [Miniflare](/workers/testing/miniflare/), a simulator that executes your Worker code using the same runtime used in production, [`workerd`](https://github.com/cloudflare/workerd). + +**You can start a local development server using:** + +1. The Cloudflare Workers CLI [**Wrangler**](/workers/wrangler/), using the built-in [`wrangler dev`](/workers/wrangler/commands/#dev) command. + + + +2. [**Vite**](https://vite.dev/), using the [**Cloudflare Vite plugin**](/workers/vite-plugin/). + + + +Both Wrangler and the Cloudflare Vite plugin use [Miniflare](/workers/testing/miniflare/) under the hood, and are developed and maintained by the Cloudflare team. For guidance on choosing when to use Wrangler versus Vite, see our guide [Choosing between Wrangler & Vite](/workers/local-development/wrangler-vs-vite/). + +- [Get started with Wrangler](/workers/wrangler/install-and-update/) +- [Get started with the Cloudflare Vite plugin](/workers/vite-plugin/get-started/) + +### Worker execution + +During **local development**, your Worker code always runs on your local machine. + +### Bindings + +When you start a local development server, Miniflare creates local simulations of Cloudflare resources, allowing your Worker code to interact with [bindings](/workers/runtime-apis/bindings/) without any code changes. Your Worker uses the exact same API calls (such as `env.MY_KV.put()`) as it would in a deployed environment, and Miniflare intercepts these calls and directs them to the locally simulated resource. + +These local resources are initially empty, but you can populate them with data, as documented in [Adding local data](/workers/local-development/local-data/). If you want to connect to remote resources (such as a real, deployed R2 bucket) while still executing your Worker code locally, see [hybrid development](/workers/development-testing/#hybrid-development). + +## Hybrid development + +With hybrid development, your Worker executes locally and bindings are configured to connect to their remote counterparts (rather than their [local simulations](/workers/development-testing/#bindings)). + +**To run a hybrid development session:** + +1. **Configure bindings**: Add the `experimental_remote: true` property to the binding definition. See [all supported bindings in hybrid development](/workers/development-testing/bindings-per-env/). +2. **Run beta command**: Use `wrangler dev --x-hybrid-dev` to start a hybrid development session. + +### Example configuration + + + +```jsonc title="wrangler.jsonc" +{ + "name": "my-worker", + "compatibility_date": "2025-06-01", + + "browser": { + "binding": "MY_BROWSER", + "experimental_remote": true, + }, + + "queues": { + "producers": [ + { + "queue": "queues-web-crawler", + "binding": "queues_web_crawler", + }, + ], + }, + + "r2_buckets": [ + { + "bucket_name": "screenshots-bucket", + "binding": "screenshots_bucket", + "preview_bucket_name": "preview-screenshots-bucket", + "experimental_remote": true, + }, + ], +} +``` + + + +In the above example, you’re able to more realistically test out and trust that any [Browser Rendering](/browser-rendering/) interactions work as intended, as well as validate the end results of the screenshots in R2 – while leaving room to rapidly iterate on the actual logic within your Worker and queues. + +### Worker execution + +During **hybrid development**, your Worker code always runs on your local machine. + +### Bindings + +For all bindings marked with `experimental_remote: true`, Miniflare routes its operations (such as `env.MY_KV.put()`) to the deployed resource. This connection is facilitated through a secure proxy mechanism provisioned on Cloudflare's network. All other bindings not explicitly configured with `experimental_remote: true` continue to use their default local simulations. Your Worker code can remain unchanged, regardless of whether the binding connects locally or remotely. + +### Targeting Preview vs. Production resources + +To protect production data, you can create and specify preview resources in your [Wrangler configuration](/workers/wrangler/configuration/), such as: + +- [Preview namespaces for KV stores](/workers/wrangler/configuration/#kv-namespaces):`preview_id`. +- [Preview buckets for R2 storage](/workers/wrangler/configuration/#r2-buckets): `preview_bucket_name`. +- [Preview database IDs for D1](/workers/wrangler/configuration/#d1-databases): `preview_database_id` + +If preview configuration is present for a binding, setting `experimental_remote: true` will make your local session connect to that designated remote preview resource. If no preview configuration is specified, `experimental_remote: true` will connect to the main remote production resource. + +**For example:** + + + +```jsonc title="wrangler.jsonc" +{ + "name": "my-worker", + "compatibility_date": "2025-06-01", + + "r2_buckets": [ + { + "bucket_name": "screenshots-bucket", + "binding": "screenshots_bucket", + "preview_bucket_name": "preview-screenshots-bucket", + "experimental_remote": true, + }, + ], +} +``` + + + +Running your local dev command `wrangler dev --x-hybrid-dev` with the above configuration means that: + +- Your Worker code runs locally +- All calls made to `env.screenshots_bucket` will use the `preview-screenshots-bucket` resource, rather than the production `screenshots-bucket`. + +### Recommended remote bindings + +We recommend configuring specific bindings to connect to their remote counterparts. These services often rely on Cloudflare's network infrastructure or have complex backends that are not fully simulated locally. + +The following bindings are recommended to have `experimental_remote: true` in your Wrangler configuration: + +#### [Browser Rendering](/workers/wrangler/configuration/#browser-rendering): + +To interact with a real headless browser for rendering. There is no current local simulation for Browser Rendering. + + +```jsonc title="wrangler.jsonc" +{ + "browser": { + "binding": "MY_BROWSER", + "experimental_remote": true + }, +} +``` + + +#### [Workers AI](/workers/wrangler/configuration/#workers-ai): + +To utilize actual AI models deployed on Cloudflare's network for inference. There is no current local simulation for Workers AI. + + +```jsonc title="wrangler.jsonc" +{ + "ai": { + "binding": "AI", + "experimental_remote": true + }, +} +``` + + +#### [Vectorize](/workers/wrangler/configuration/#vectorize-indexes): + +To connect to your production Vectorize indexes for accurate vector search and similarity operations. There is no current local simulation for Vectorize. + + +```jsonc title="wrangler.jsonc" +{ + "vectorize": [ + { + "binding": "MY_VECTORIZE_INDEX", + "index_name": "my-prod-index", + "experimental_remote": true + } + ], +} +``` + + +#### [mTLS](/workers/wrangler/configuration/#mtls-certificates): + +To verify that the certificate exchange and validation process work as expected. There is no current local simulation for mTLS bindings. + + +```jsonc title="wrangler.jsonc" +{ + "mtls_certificates": [ + { + "binding": "MY_CLIENT_CERT_FETCHER", + "certificate_id": "", + "experimental_remote": true + + } + ] + +} + +``` + + +#### [Images](/workers/wrangler/configuration/#images): + +To connect to a high-fidelity version of the Images API, and verify that all transformations work as expected. Local simulation for Cloudflare Images is [limited with only a subset of features](/images/transform-images/bindings/#interact-with-your-images-binding-locally). + + +```jsonc title="wrangler.jsonc" +{ + "images": { + "binding": "IMAGES" , + "experimental_remote": true + } +} +``` + + + + + +### Unsupported remote bindings + +While hybrid development allows many bindings to connect to remote resources, certain bindings are not supported for remote connections during local development (`experimental_remote: true`). These will always use local simulations or local values. + +If `experimental_remote: true` is specified in Wrangler configuration for any of the following unsupported binding types, Cloudflare **will issue an error**. See [all supported and unsupported bindings in hybrid development](/workers/development-testing/bindings-per-env/). + +- [**Durable Objects**](/workers/wrangler/configuration/#durable-objects): Durable Objects have synchronous operational aspects in their API. The current hybrid development proxy mechanism primarily supports asynchronous operations. Enabling remote connections for Durable Objects may be supported in the future, but currently will always run locally. + +- [**Environment Variables (`vars`)**](/workers/wrangler/configuration/#environment-variables): Environment variables are intended to be distinct between local development and deployed environments (`production`, `preview`). They are easily configurable locally (such as in a `.dev.vars` file or directly in Wrangler configuration). + +- [**Secrets**](/workers/wrangler/configuration/#secrets): Like environment variables, secrets are expected to have different values in local development versus deployed environments for security reasons. Use `.dev.vars` for local secret management. + +- **[Static Assets](/workers/wrangler/configuration/#assets)**: Static assets are always served from your local disk during development for speed and direct feedback on changes. + +- [**Version Metadata**](/workers/runtime-apis/bindings/version-metadata/): Since your Worker code is running locally, version metadata (like commit hash, version tags) associated with a specific deployed version is not applicable or accurate. + +- [**Analytics Engine**](/analytics/analytics-engine/): Local development sessions typically don't contribute data directly to production Analytics Engine. + +- [**Hyperdrive**](/workers/wrangler/configuration/#hyperdrive): This is being actively worked on, but is currently unsupported. +- [**Rate Limiting**](/workers/runtime-apis/bindings/rate-limit/#configuration): Local development sessions typically should not share or affect rate limits of your deployed Workers. Rate limiting logic should be tested against local simulations. + + + +### Important Considerations + +- **Data modification**: Operations (writes, deletes, updates) on bindings connected remotely will affect your actual data in the targeted Cloudflare resource (be it preview or production). + +- **Billing**: Interactions with remote Cloudflare services through these connections will incur standard operational costs for those services (such as KV operations, R2 storage/operations, AI requests, D1 usage). + +- **Network latency**: Expect network latency for operations on these remotely connected bindings, as they involve communication over the internet. + +- **Environment Variables & Secrets**: Standard environment variables (from `vars`) and Secrets always use their locally defined values during local development. The `experimental_remote: true` flag does not apply to them. + +### API + +TO-DO + +## Remote development (Legacy) + +Separate from Miniflare-powered local development, Wrangler also offers a fully remote development mode via [`wrangler dev --remote`](/workers/wrangler/commands/#dev). Remote development is [**not** supported in the Vite plugin](/workers/local-development/wrangler-vs-vite/). + + + +### Worker execution + +During **remote development**, all of your Worker code is uploaded to a temporary preview environment on Cloudflare's infrastructure, and changes to your code are automatically uploaded as you save. + +### Bindings + +When using remote development, all bindings automatically connect to their remote resources. Unlike local and hybrid development modes, you cannot configure bindings to use local simulations - they will always use the deployed resources on Cloudflare's network. + +### When to use Remote development + +- For most development tasks, the most efficient and productive experience will be local development along with [hybrid development](/workers/development-testing/#hybrid-development) when needed. +- You may want to use `wrangler dev --remote` for testing features or behaviors that are highly specific to Cloudflare's network and cannot be adequately simulated locally or tested via remote bindings. + +### Considerations + +- Iteration is significantly slower than local development due to the upload/deployment step for each change. + +### Isolating from Production + +To protect production data, you can specify preview resources in your [Wrangler configuration](/workers/wrangler/configuration/), such as: + +- [Preview namespaces for KV stores](/workers/wrangler/configuration/#kv-namespaces):`preview_id`. + - This option is **required** when using `wrangler dev --remote`. +- [Preview buckets for R2 storage](/workers/wrangler/configuration/#r2-buckets): `preview_bucket_name`. +- [Preview database IDs for D1](/workers/wrangler/configuration/#d1-databases): `preview_database_id` + +This separation ensures your development activities don't impact production data while still providing a realistic testing environment. + +### Limitations + +- When you run a remote development session using the `--remote` flag, a limit of 50 [routes](/workers/configuration/routing/routes/) per zone is enforced. Learn more in[ Workers platform limits](/workers/platform/limits/#number-of-routes-per-zone-when-using-wrangler-dev---remote). diff --git a/src/content/docs/workers/local-development/local-data.mdx b/src/content/docs/workers/development-testing/local-data.mdx similarity index 99% rename from src/content/docs/workers/local-development/local-data.mdx rename to src/content/docs/workers/development-testing/local-data.mdx index b2f00f8f26edb3..187b96922437ee 100644 --- a/src/content/docs/workers/local-development/local-data.mdx +++ b/src/content/docs/workers/development-testing/local-data.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Adding local data sidebar: - order: 2 + order: 4 head: [] description: Populating local resources with data --- diff --git a/src/content/docs/workers/development-testing/testing.mdx b/src/content/docs/workers/development-testing/testing.mdx new file mode 100644 index 00000000000000..37229e3b1f69bf --- /dev/null +++ b/src/content/docs/workers/development-testing/testing.mdx @@ -0,0 +1,7 @@ +--- +pcx_content_type: navigation +title: Testing +external_link: /workers/testing/ +sidebar: + order: 7 +--- \ No newline at end of file diff --git a/src/content/docs/workers/development-testing/vite-plugin.mdx b/src/content/docs/workers/development-testing/vite-plugin.mdx new file mode 100644 index 00000000000000..a6b768da089f75 --- /dev/null +++ b/src/content/docs/workers/development-testing/vite-plugin.mdx @@ -0,0 +1,7 @@ +--- +pcx_content_type: navigation +title: Vite Plugin +external_link: /workers/vite-plugin/ +sidebar: + order: 1 +--- \ No newline at end of file diff --git a/src/content/docs/workers/local-development/wrangler-vs-vite.mdx b/src/content/docs/workers/development-testing/wrangler-vs-vite.mdx similarity index 99% rename from src/content/docs/workers/local-development/wrangler-vs-vite.mdx rename to src/content/docs/workers/development-testing/wrangler-vs-vite.mdx index ea046fe2586a98..734a453280ee1e 100644 --- a/src/content/docs/workers/local-development/wrangler-vs-vite.mdx +++ b/src/content/docs/workers/development-testing/wrangler-vs-vite.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Choosing between Wrangler & Vite sidebar: - order: 4 + order: 3 head: [] description: Choosing between Wrangler and Vite for local development --- diff --git a/src/content/docs/workers/local-development/index.mdx b/src/content/docs/workers/local-development/index.mdx deleted file mode 100644 index 79048b4e7e8f51..00000000000000 --- a/src/content/docs/workers/local-development/index.mdx +++ /dev/null @@ -1,300 +0,0 @@ ---- -pcx_content_type: navigation -title: Local development -sidebar: - order: 6 -head: [] -description: Develop your Workers locally. ---- - -import { - Details, - LinkCard, - Render, - PackageManagers, - WranglerConfig, - Aside, -} from "~/components"; - -Local development allows you to build, run, and test your Worker code on your own machine before deploying it to Cloudflare's network. This is made possible through [Miniflare](/workers/testing/miniflare/), a simulator that executes your Worker code using the same runtime used in production, [`workerd`](https://github.com/cloudflare/workerd). By default, your Worker's bindings connect to locally simulated resources, but can be configured to interact with real, production resources. - -## Start a development server - -You can start a local development server using: - -1. Our official CLI [**Wrangler**](/workers/wrangler/), using the built-in [`wrangler dev`](/workers/wrangler/commands/#dev) command. - - - -2. [**Vite**](https://vite.dev/), using the [**Cloudflare Vite plugin**](/workers/vite-plugin/). - - - -Both Wrangler and the Cloudflare Vite plugin both use Miniflare under the hood, and are developed and maintained by the Cloudflare team. For guidance on choosing when to use Wrangler versus Vite, see our guide [Choosing between Wrangr & Vite](/workers/local-development/wrangler-vs-vite/). - -- [Get started with Wrangler](/workers/wrangler/install-and-update/) -- [Get started with the Cloudflare Vite plugin](/workers/vite-plugin/get-started/) - -### Default Behavior (Fully local) - -By default, running `wrangler dev` / `vite dev` (when using the [Vite plugin](/workers/vite-plugin/get-started/)) means that: - -- Your Worker code runs on your local machine. -- All resources your Worker is bound to in your [Wrangler configuration](/workers/wrangler/configuration/) are simulated locally. - -### Bindings during local development - -[Bindings](/workers/runtime-apis/bindings/) are interfaces that allow your Worker to interact with various Cloudflare resources (like [KV namespaces](/kv), [R2 buckets](/r2), [D1 databases](/d1), [Queues](/queues/), [Durable Objects](/durable-objects/), etc). In your Worker code, these are accessed via the `env` object (such as `env.MY_KV`). - -During local development, your Worker code interacts with these bindings using the exact same API calls (such as `env.MY_KV.put()`) as it would in a deployed environment. Miniflare intercepts these calls and directs them to the locally simulated resource. These local resources are initially empty, but you can populate them with data, as documented in [Adding local data](/workers/local-development/local-data/). - -- By default, bindings connect to **local resource simulations** (except for [AI bindings](/workers-ai/configuration/bindings/), as AI models always run remotely). -- You can override this default behavior and **connect to the remote resource**, on a per-binding basis. This lets you connect to real, production resources while still running your Worker code locally. - -## Connect to remote resources (Hybrid) - -There are times when you might want to connect to the real, remote resource during local development _instead_ of the locally simulated resource. You can configure this on a per-binding basis, by setting `remote: true` in the binding definition. - -**For example:** - - - -```jsonc title="wrangler.jsonc" -{ - "name": "my-worker", - "compatibility_date": "2025-06-01", - - "browser": { - "binding": "MY_BROWSER", - "remote": true, - }, - - "queues": { - "producers": [ - { - "queue": "queues-web-crawler", - "binding": "queues_web_crawler", - "remote": false, // Default value, but here for illustration - }, - ], - "consumers": [ - { - "queue": "queues-web-crawler", - "max_batch_size": 5, - "max_batch_timeout": 30, - "max_retries": 3, - "dead_letter_queue": "web-crawler-dlq", - "remote": false, // Default value, but here for illustration - }, - ], - }, - - "r2_buckets": [ - { - "bucket_name": "screenshots-bucket", - "binding": "screenshots_bucket", - "preview_bucket_name": "preview-screenshots-bucket", - "remote": true, - }, - ], -} -``` - - - -In the above example, you’re able to more realistically test out and trust that any [Browser Rendering](/browser-rendering/) interactions work as intended, as well as validate the end results of the screenshots in R2 – while leaving room to rapidly iterate on the actual logic within your Worker and queues. - - - -### How it works - -When you run you local dev command and a binding definition includes `remote: true`, the following takes place: - -- Your Worker's code continues to run on your machine within `workerd`, managed by Miniflare (whether initiated by Wrangler or Vite). -- For all bindings marked with `remote: true`, Miniflare routes its operations (such as `env.MY_KV.put()`) to the deployed resource. This connection is facilitated through a secure proxy mechanism provisioned on Cloudflare's network. -- All other bindings not explicitly configured with `remote: true` continue to use their default local simulations. -- Your Worker code remains unchanged, regardless of whether the bindings is fully local or connected remotely. - -### Targeting Preview vs. Production resources - -To protect production data, you can create and specify preview resources in your [Wrangler configuration](/workers/wrangler/configuration/), such as: - -- [Preview namespaces for KV stores](/workers/wrangler/configuration/#kv-namespaces):`preview_id`. -- [Preview buckets for R2 storage](/workers/wrangler/configuration/#r2-buckets): `preview_bucket_name`. -- [Preview database IDs for D1](/workers/wrangler/configuration/#d1-databases): `preview_database_id` - -If preview configuration is present for a binding, setting `remote: true` will make your local session connect to that designated remote preview resource. -If no preview configuration is specified, `remote: true` will connect to the main remote production resource. - -**For example:** - - - -```jsonc title="wrangler.jsonc" -{ - "name": "my-worker", - "compatibility_date": "2025-06-01", - - "r2_buckets": [ - { - "bucket_name": "screenshots-bucket", - "binding": "screenshots_bucket", - "preview_bucket_name": "preview-screenshots-bucket", - "remote": true, - }, - ], -} -``` - - - -Running your local dev command (`wrangler dev` / `vite dev`) with the above configuration means that: - -- Your Worker code runs locally -- All calls made to `env.screenshots_bucket` will use the `preview-screenshots-bucket` resource, rather than the production `screenshots-bucket`. - -### Recommended remote bindings - -We recommend configuring specific bindings to connect to their remote counterparts. These services often rely on Cloudflare's network infrastructure or have complex backends that are not fully simulated locally. - -The following bindings are recommended to have `remote: true` in your Wrangler configuration: - -- [**Browser Rendering**](/workers/wrangler/configuration/#browser-rendering): To interact with a real headless browser for rendering. - -- [**Workers AI**](/workers/wrangler/configuration/#workers-ai): To utilize actual AI models deployed on Cloudflare's network for inference. - -- [**Vectorize**](/workers/wrangler/configuration/#vectorize-indexes): To connect to your production Vectorize indexes for accurate vector search and similarity operations. - -- **Service bindings to [mTLS-enabled services](/workers/wrangler/configuration/#mtls-certificates)**: If you have a service binding that points to a deployed Worker or service that requires mTLS authentication from its clients, setting `remote: true` for that service binding is recommended for realistic end-to-end testing. Your Worker would then use an `mtls_certificates` binding to make the call. - -#### Behavior and configuration: - -- If `remote: true` is not specified for Browser Rendering, Vectorize, or for a service binding that is intended to call an mTLS-protected remote service, Cloudflare will issue a warning. This prompts you to consider enabling it for a more production-like testing experience. -- For Workers AI, if the `ai.remote` property is set to `false`, Cloudflare will produce an error. If the property is omitted, Cloudflare will connect to the remote resource and issue a warning to add the property to configuration. - - -```jsonc title="wrangler.jsonc" -{ - "name": "my-worker", - "compatibility_date": "2025-06-01", - // ... other configurations ... - "browser": { - "binding": "MY_BROWSER", - "remote": true // Recommended - }, - "vectorize": [ - { - "binding": "MY_VECTORIZE_INDEX", - "index_name": "my-prod-index", - "remote": true // Recommended - } - ], - "services": [ - { - "binding": "API_SERVICE_REQUIRING_MTLS", // A service this worker calls - "service": "deployed-api-worker-expecting-mtls", // This target service expects mTLS - "remote": true // Recommended - } - ], - "ai": { - "binding": "AI", // Access as env.AI - "remote": true // Required; setting to false or omitting will error - }, - "mtls_certificates": [ // Defines how this worker can present a client certificate - { - "binding": "MY_CLIENT_CERT_FETCHER", // Access as env.MY_CLIENT_CERT_FETCHER - "certificate_id": "" - // Note: 'remote: true' is NOT applicable here. This binding provides a - // an object that has a `.fetch()` method. - } - ] - // Note: For other services like KV, R2, D1, Queues, 'remote: true' is optional -} -``` - - -### Limitations - Unsupported remote bindings - -While the hybrid approach allows many bindings to connect to remote resources, certain bindings are not supported for remote connections during local development (`remote: true`). These will always use local simulations or local values. - -If `remote: true` is specified in Wrangler configuration for any of the following unsupported binding types, Cloudflare will issue an error. - -- [**Durable Objects**](/workers/wrangler/configuration/#durable-objects): Durable Objects have synchronous operational aspects in their API. The current hybrid development proxy mechanism primarily supports asynchronous operations. Enabling remote connections for Durable Objects may be supported in the future, but currently will always run locally. - -- [**Environment Variables (`vars`)**](/workers/wrangler/configuration/#environment-variables): Environment variables are intended to be distinct between local development and deployed environments (`production`, `preview`). They are easily configurable locally (such as in a `.dev.vars` file or directly in Wrangler configuration. - -- [**Secrets**](/workers/wrangler/configuration/#secrets): Like environment variables, secrets are expected to have different values in local development versus deployed environments for security reasons. Use `.dev.vars` for local secret management. - -- **[Assets (Static Assets)](//workers/wrangler/configuration/#assets)**: Static assets are always served from your local disk during development for speed and direct feedback on changes. - -- [**Version Metadata**](/workers/runtime-apis/bindings/version-metadata/): Since your Worker code is running locally, version metadata (like commit hash, version tags) associated with a specific deployed version is not applicable or accurate. - -- [**Analytics Engine**](/analytics/analytics-engine/): Local development sessions typically don't contribute data directly to production Analytics Engine. - -- [**Hyperdrive**](/workers/wrangler/configuration/#hyperdrive): This is being actively worked on, but is currently unsupported. -- [**Rate Limiting**](/workers/runtime-apis/bindings/rate-limit/#configuration): Local development sessions typically should not share or affect rate limits of your deployed Workers. Rate limiting logic should be tested against local simulations. - - - -### Important Considerations - -- **Data modification**: Operations (writes, deletes, updates) on bindings connected remotely will affect your actual data in the targeted Cloudflare resource (be it preview or production). - -- **Billing**: Interactions with remote Cloudflare services through these connections will incur standard operational costs for those services (such as KV operations, R2 storage/operations, AI requests, D1 usage). - -- **Network latency**: Expect network latency for operations on these remotely connected bindings, as they involve communication over the internet. - -- **Environment Variables & Secrets**: Standard environment variables (from [vars]) and Secrets always use their locally defined values during local development. The `remote: true` flag does not apply to them. - -### API - -TO-DO - -## Remote development - -Separate from Miniflare-powered local development, Wrangler also offers a fully remote development mode via [`wrangler dev --remote`](/workers/wrangler/commands/#dev). Remote development is [**not** supported in the Vite plugin](/workers/local-development/wrangler-vs-vite/). - - - -### How It Works - -The `wrangler dev --remote` command creates a temporary preview deployment on Cloudflare's infrastructure. - -When you run `wrangler dev --remote`: - -- All of your code is uploaded to a temporary preview environment on Cloudflare's infrastructure. -- Changes to your code are automatically uploaded as you save. -- All requests and execution happen on Cloudflare's global network. -- The preview automatically terminates when you exit the command. - -### When to use Remote development - -- For most development tasks, the most efficient and productive experience will be local development along with [connections to remote resources](/workers/local-development/#connect-to-remote-resources-hybrid). -- You may want to use `wrangler dev --remote` for testing features or behaviors that are highly specific to Cloudflare's network and cannot be adequately simulated locally or tested via hybrid connections. - -### Considerations - -- Iteration is significantly slower than local development due to the upload/deployment step for each change. - -### Isolating from Production - -To protect production data, you can specify preview resources in your [Wrangler configuration](/workers/wrangler/configuration/), such as: - -- [Preview namespaces for KV stores](/workers/wrangler/configuration/#kv-namespaces):`preview_id`. - - This option is **required** when using `wrangler dev --remote`. -- [Preview buckets for R2 storage](/workers/wrangler/configuration/#r2-buckets): `preview_bucket_name`. -- [Preview database IDs for D1](/workers/wrangler/configuration/#d1-databases): `preview_database_id` - -This separation ensures your development activities don't impact production data while still providing a realistic testing environment. - -### Limitations - -- When you run a remote development session using the `--remote` flag, a limit of 50 [routes](/workers/configuration/routing/routes/) per zone is enforced. Learn more in[ Workers platform limits](/workers/platform/limits/#number-of-routes-per-zone-when-using-wrangler-dev---remote). diff --git a/src/content/partials/workers/bindings_per_env.mdx b/src/content/partials/workers/bindings_per_env.mdx index d5ef6c12a097a9..8dbb51887867c2 100644 --- a/src/content/partials/workers/bindings_per_env.mdx +++ b/src/content/partials/workers/bindings_per_env.mdx @@ -2,29 +2,33 @@ {} --- -**Local Development:** Includes [`wrangler dev`](/workers/wrangler/commands/#dev) (without the `--remote` flag) and the [Cloudflare Vite plugin](/workers/vite-plugin/). This mode simulates the Cloudflare Workers environment locally. - -**Remote Development:** Uses [`wrangler dev --remote`](/workers/wrangler/commands/#dev)), deploying your code to Cloudflare’s infrastructure during development. This ensures all bindings and resources match production conditions. There is **no Vite plugin equivalent** for testing remote resources. - -| Binding | Local (Wrangler & Vite) | Remote (Wrangler only) | -| --------------------------------------- | :---------------------: | :--------------------: | -| **AI** | ✅[^1] | ✅ | -| **Assets** | ✅ | ✅ | -| **Analytics Engine** | ✅[^4] | ✅ | -| **Browser Rendering** | ❌ | ✅ | -| **D1** | ✅ | ✅ | -| **Durable Objects** | ✅ | ✅ | -| **Email Bindings** | ✅ | ✅ | -| **Hyperdrive** | ✅[^2] | ✅ | -| **Images** | ✅ | ✅ | -| **KV** | ✅ | ✅ | -| **mTLS** | ❌ | ✅ | -| **Queues** | ✅ | ❌ | -| **R2** | ✅ | ✅ | -| **Rate Limiting** | ✅ | ✅ | -| **Service Bindings (multiple Workers)** | ✅ | ✅ | -| **Vectorize** | ✅[^3] | ✅ | -| **Workflows** | ✅ | ❌ | +The three development modes differ in [**where your Worker executes** and **how bindings connect**](/workers/development-testing/#core-concepts): + +**Local Development:** [Worker execution](/workers/development-testing/#worker-execution) runs locally on your machine. [Bindings](/workers/development-testing/#bindings) connect to local resource simulations. Supported in both [`wrangler dev`](/workers/wrangler/commands/#dev) and the [Cloudflare Vite plugin](/workers/vite-plugin/). + +**Hybrid Development:** [Worker execution](/workers/development-testing/#worker-execution-1) runs locally on your machine. [Bindings](/workers/development-testing/#bindings-1) can connect to local simulations (default) or remote resources via `experimental_remote: true` configuration. Supported in both [`wrangler dev --x-hybrid-dev`](/workers/development-testing/#hybrid-development) and the Cloudflare Vite plugin. + +**Remote Development:** [Worker execution](/workers/development-testing/#worker-execution-2) runs on Cloudflare's infrastructure. [Bindings](/workers/development-testing/#bindings-2) always connect to remote resources. Supported only in [`wrangler dev --remote`](/workers/wrangler/commands/#dev) - there is **no Vite plugin equivalent**. + +| Binding | Local dev | Hybrid dev | Remote dev | +| --------------------------------------- | :-------: | :--------: | :--------: | +| **AI** | ✅[^1] | ✅ [**Recommended**](/workers/development-testing/#workers-ai) | ✅ | +| **Assets** | ✅ | ❌ | ✅ | +| **Analytics Engine** | ✅[^4] | ❌ | ✅ | +| **Browser Rendering** | ❌ | ✅ [**Recommended**](/workers/development-testing/#browser-rendering) | ✅ | +| **D1** | ✅ | ✅ | ✅ | +| **Durable Objects** | ✅ | ❌ | ✅ | +| **Email Bindings** | ✅ | ✅ | ✅ | +| **Hyperdrive** | ✅[^2] | ❌ | ✅ | +| **Images** | ✅ | ✅ [**Recommended**](/workers/development-testing/#images) | ✅ | +| **KV** | ✅ | ✅ | ✅ | +| **mTLS** | ❌ | ✅ [**Recommended**](/workers/development-testing/#mtls) | ✅ | +| **Queues** | ✅ | ✅ | ❌ | +| **R2** | ✅ | ✅ | ✅ | +| **Rate Limiting** | ✅ | ❌ | ✅ | +| **Service Bindings (multiple Workers)** | ✅ | ✅ | ✅ | +| **Vectorize** | ✅[^3] | ✅ [**Recommended**](/workers/development-testing/#vectorize) | ✅ | +| **Workflows** | ✅ | ✅ | ❌ | [^1]: Using Workers AI always accesses your Cloudflare account in order to run AI models and will incur usage charges, even in local development. @@ -34,12 +38,6 @@ [^4]: Analytics Engine is supported in local development with Wrangler but is not currently supported in the Vite plugin. -> **Tip:** If you need to use any bindings marked with ❌ under local development, run: -> -> ```bash -> wrangler dev --remote -> ``` -> -> This command allows you to develop against remote resources and data stored on Cloudflare's network. +> **Tip:** If you have a binding with no local dev support, try [hybrid development](/workers/development-testing/#hybrid-development) to connect to the remote resource while keeping your Worker code running locally. ---- +--- \ No newline at end of file From 2e87f689556c283191afc8b598544e6683d72bd6 Mon Sep 17 00:00:00 2001 From: korinne Date: Tue, 17 Jun 2025 15:40:25 -0700 Subject: [PATCH 05/12] updates naming to remote bindings, adds API section --- .../workers/development-testing/index.mdx | 279 ++++++++++++------ .../partials/workers/bindings_per_env.mdx | 80 +++-- 2 files changed, 234 insertions(+), 125 deletions(-) diff --git a/src/content/docs/workers/development-testing/index.mdx b/src/content/docs/workers/development-testing/index.mdx index ec3a31428522a2..46de51d9a2906d 100644 --- a/src/content/docs/workers/development-testing/index.mdx +++ b/src/content/docs/workers/development-testing/index.mdx @@ -4,7 +4,7 @@ title: Development & testing sidebar: order: 6 head: [] -description: Develop and test your Workers locally or with hybrid approaches. +description: Develop and test your Workers locally. --- import { @@ -17,9 +17,13 @@ import { InlineBadge, CardGrid, Card, + Type, + TypeScriptExample, } from "~/components"; -Cloudflare Workers offers three distinct development modes to build, run, and test your Worker code before deploying to production. Choose from [fully **local development**](/workers/development-testing/#local-development) with simulated resources, [**hybrid development**](/workers/development-testing/#hybrid-development) that combines local execution with remote resource connections, or [legacy **remote development**](/workers/development-testing/#remote-development-legacy) that runs entirely on Cloudflare's infrastructure. +You can build, run, and test your Worker code on your own local machine before deploying it to Cloudflare's network. This is made possible through [Miniflare](/workers/testing/miniflare/), a simulator that executes your Worker code using the same runtime used in production, [`workerd`](https://github.com/cloudflare/workerd). + +By default, your Worker's bindings connect to locally simulated resources, but can be configured to interact with the real, production resource. ## Core concepts @@ -29,42 +33,10 @@ When developing Workers, it's important to understand two distinct concepts: - **Worker execution**: Where your Worker code actually runs (on your local machine vs on Cloudflare's infrastructure). -- **Bindings**: How your Worker interacts with Cloudflare resources (like [KV namespaces](/kv), [R2 buckets](/r2), [D1 databases](/d1), [Queues](/queues/), [Durable Objects](/durable-objects/), etc). In your Worker code, these are accessed via the `env` object (such as `env.MY_KV`). - -While these are independent concepts, **where your Worker** runs and **how bindings connect** determines which [development mode](/workers/development-testing/#development-modes) you're using. - -### Development Modes - -Based on where your Worker runs and how bindings connect, there are three development modes: - - - **Worker execution**: Runs locally on your machine via `wrangler dev` / [`vite dev`](/workers/vite-plugin/get-started/). - - **Bindings**: Connect to local resource simulations by default. - - [Learn more.](/workers/development-testing/#local-development) - - - - **Worker execution**: Runs locally on your machine, via the experimental `wrangler dev --x-hybrid-dev` command. - - **Bindings**: Can connect to local resource simulations (default) or be configured to connect to the deployed, remote resource. - - [Learn more.](/workers/development-testing/#hybrid-development) - - - - **Worker execution**: Runs on Cloudflare's infrastructure via `wrangler dev --remote`. - - **Bindings**: Always connect to remote resources. - - [Learn more.](/workers/development-testing/#remote-development-legacy) - +- [**Bindings**](/workers/runtime-apis/bindings/): How your Worker interacts with Cloudflare resources (like [KV namespaces](/kv), [R2 buckets](/r2), [D1 databases](/d1), [Queues](/queues/), [Durable Objects](/durable-objects/), etc). In your Worker code, these are accessed via the `env` object (such as `env.MY_KV`). ## Local development -Local development allows you to build, run, and test your Worker code on your own machine before deploying it to Cloudflare's network. This is made possible through [Miniflare](/workers/testing/miniflare/), a simulator that executes your Worker code using the same runtime used in production, [`workerd`](https://github.com/cloudflare/workerd). - **You can start a local development server using:** 1. The Cloudflare Workers CLI [**Wrangler**](/workers/wrangler/), using the built-in [`wrangler dev`](/workers/wrangler/commands/#dev) command. @@ -75,29 +47,30 @@ Local development allows you to build, run, and test your Worker code on your ow -Both Wrangler and the Cloudflare Vite plugin use [Miniflare](/workers/testing/miniflare/) under the hood, and are developed and maintained by the Cloudflare team. For guidance on choosing when to use Wrangler versus Vite, see our guide [Choosing between Wrangler & Vite](/workers/local-development/wrangler-vs-vite/). +Both Wrangler and the Cloudflare Vite plugin use [Miniflare](/workers/testing/miniflare/) under the hood, and are developed and maintained by the Cloudflare team. For guidance on choosing when to use Wrangler versus Vite, see our guide [Choosing between Wrangler & Vite](/workers/development-testing/wrangler-vs-vite/). - [Get started with Wrangler](/workers/wrangler/install-and-update/) - [Get started with the Cloudflare Vite plugin](/workers/vite-plugin/get-started/) -### Worker execution +### Defaults -During **local development**, your Worker code always runs on your local machine. +By default, running `wrangler dev` / `vite dev` (when using the [Vite plugin](/workers/vite-plugin/get-started/)) means that: -### Bindings +- Your Worker code runs on your local machine. +- All resources your Worker is bound to in your [Wrangler configuration](/workers/wrangler/configuration/) are simulated locally. -When you start a local development server, Miniflare creates local simulations of Cloudflare resources, allowing your Worker code to interact with [bindings](/workers/runtime-apis/bindings/) without any code changes. Your Worker uses the exact same API calls (such as `env.MY_KV.put()`) as it would in a deployed environment, and Miniflare intercepts these calls and directs them to the locally simulated resource. +### Bindings during local development -These local resources are initially empty, but you can populate them with data, as documented in [Adding local data](/workers/local-development/local-data/). If you want to connect to remote resources (such as a real, deployed R2 bucket) while still executing your Worker code locally, see [hybrid development](/workers/development-testing/#hybrid-development). +[Bindings](/workers/runtime-apis/bindings/) are interfaces that allow your Worker to interact with various Cloudflare resources (like [KV namespaces](/kv), [R2 buckets](/r2), [D1 databases](/d1), [Queues](/queues/), [Durable Objects](/durable-objects/), etc). In your Worker code, these are accessed via the `env` object (such as `env.MY_KV`). -## Hybrid development +During local development, your Worker code interacts with these bindings using the exact same API calls (such as `env.MY_KV.put()`) as it would in a deployed environment. These local resources are initially empty, but you can populate them with data, as documented in [Adding local data](/workers/development-testing/local-data/). -With hybrid development, your Worker executes locally and bindings are configured to connect to their remote counterparts (rather than their [local simulations](/workers/development-testing/#bindings)). +- By default, bindings connect to **local resource simulations** (except for [AI bindings](/workers-ai/configuration/bindings/), as AI models always run remotely). +- You can override this default behavior and **connect to the remote resource**, on a per-binding basis. This lets you connect to real, production resources while still running your Worker code locally. -**To run a hybrid development session:** +## Remote bindings -1. **Configure bindings**: Add the `experimental_remote: true` property to the binding definition. See [all supported bindings in hybrid development](/workers/development-testing/bindings-per-env/). -2. **Run beta command**: Use `wrangler dev --x-hybrid-dev` to start a hybrid development session. +**Remote bindings** are bindings that are configured to connect to the deployed, remote resource during local development _instead_ of the locally simulated resource. You can configure remote bindings by setting `experimental_remote: true` in the binding definition. ### Example configuration @@ -108,25 +81,10 @@ With hybrid development, your Worker executes locally and bindings are configure "name": "my-worker", "compatibility_date": "2025-06-01", - "browser": { - "binding": "MY_BROWSER", - "experimental_remote": true, - }, - - "queues": { - "producers": [ - { - "queue": "queues-web-crawler", - "binding": "queues_web_crawler", - }, - ], - }, - "r2_buckets": [ { "bucket_name": "screenshots-bucket", "binding": "screenshots_bucket", - "preview_bucket_name": "preview-screenshots-bucket", "experimental_remote": true, }, ], @@ -135,17 +93,54 @@ With hybrid development, your Worker executes locally and bindings are configure -In the above example, you’re able to more realistically test out and trust that any [Browser Rendering](/browser-rendering/) interactions work as intended, as well as validate the end results of the screenshots in R2 – while leaving room to rapidly iterate on the actual logic within your Worker and queues. +When remote bindings are configured, your Worker still **executes locally**, only the underlying resources your bindings connect to change. For all bindings marked with `experimental_remote: true`, Miniflare will route its operations (such as `env.MY_KV.put()`) to the deployed resource. All other bindings not explicitly configured with `experimental_remote: true` continue to use their default local simulations. + +### Using Wrangler with remote bindings + +If you're using [Wrangler](/workers/wrangler/) for local development and have remote bindings configured, you'll need to use the following experimental command: -### Worker execution + -During **hybrid development**, your Worker code always runs on your local machine. +### Using Vite with remote bindings -### Bindings +If you're using Vite via [the Cloudflare Vite plugin](/workers/vite-plugin/), you'll need to add support for remote bindings in your Vite configuration (`vite.config.ts`): -For all bindings marked with `experimental_remote: true`, Miniflare routes its operations (such as `env.MY_KV.put()`) to the deployed resource. This connection is facilitated through a secure proxy mechanism provisioned on Cloudflare's network. All other bindings not explicitly configured with `experimental_remote: true` continue to use their default local simulations. Your Worker code can remain unchanged, regardless of whether the binding connects locally or remotely. +```ts title="vite.config.ts" {10} +import { cloudflare } from "@cloudflare/vite-plugin"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + cloudflare({ + configPath: "./entry-worker/wrangler.jsonc", + inspectorPort: false, + persistState: false, + experimental: { remoteBindings: true }, + }), + ], +}); +``` -### Targeting Preview vs. Production resources +### Using Vitest with remote bindings + +You can also use Vitest with configured remote bindings by enabling support in your Vitest configuration file (`vitest.config.ts`): + +```ts title="vitest.config.ts" {7} +import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config"; + +export default defineWorkersConfig({ + test: { + poolOptions: { + workers: { + experimental_remoteBindings: true, + wrangler: { configPath: "./wrangler.jsonc" }, + }, + }, + }, +}); +``` + +### Targeting preview resources To protect production data, you can create and specify preview resources in your [Wrangler configuration](/workers/wrangler/configuration/), such as: @@ -153,7 +148,7 @@ To protect production data, you can create and specify preview resources in your - [Preview buckets for R2 storage](/workers/wrangler/configuration/#r2-buckets): `preview_bucket_name`. - [Preview database IDs for D1](/workers/wrangler/configuration/#d1-databases): `preview_database_id` -If preview configuration is present for a binding, setting `experimental_remote: true` will make your local session connect to that designated remote preview resource. If no preview configuration is specified, `experimental_remote: true` will connect to the main remote production resource. +If preview configuration is present for a binding, setting `experimental_remote: true` will ensure that remote bindings connect to that designated remote preview resource. **For example:** @@ -177,7 +172,7 @@ If preview configuration is present for a binding, setting `experimental_remote: -Running your local dev command `wrangler dev --x-hybrid-dev` with the above configuration means that: +Running `wrangler dev --x-remote-bindings` with the above configuration means that: - Your Worker code runs locally - All calls made to `env.screenshots_bucket` will use the `preview-screenshots-bucket` resource, rather than the production `screenshots-bucket`. @@ -254,7 +249,7 @@ To verify that the certificate exchange and validation process work as expected. } -``` +```` #### [Images](/workers/wrangler/configuration/#images): @@ -269,7 +264,7 @@ To connect to a high-fidelity version of the Images API, and verify that all tra "experimental_remote": true } } -``` +```` @@ -283,13 +278,13 @@ If a Workers AI binding has `experimental_remote` set to `false`, Cloudflare wil ### Unsupported remote bindings -While hybrid development allows many bindings to connect to remote resources, certain bindings are not supported for remote connections during local development (`experimental_remote: true`). These will always use local simulations or local values. +Certain bindings are not supported for remote connections during local development (`experimental_remote: true`). These will always use local simulations or local values. -If `experimental_remote: true` is specified in Wrangler configuration for any of the following unsupported binding types, Cloudflare **will issue an error**. See [all supported and unsupported bindings in hybrid development](/workers/development-testing/bindings-per-env/). +If `experimental_remote: true` is specified in Wrangler configuration for any of the following unsupported binding types, Cloudflare **will issue an error**. See [all supported and unsupported bindings for remote bindings](/workers/development-testing/bindings-per-env/). -- [**Durable Objects**](/workers/wrangler/configuration/#durable-objects): Durable Objects have synchronous operational aspects in their API. The current hybrid development proxy mechanism primarily supports asynchronous operations. Enabling remote connections for Durable Objects may be supported in the future, but currently will always run locally. +- [**Durable Objects**](/workers/wrangler/configuration/#durable-objects): Enabling remote connections for Durable Objects may be supported in the future, but currently will always run locally. -- [**Environment Variables (`vars`)**](/workers/wrangler/configuration/#environment-variables): Environment variables are intended to be distinct between local development and deployed environments (`production`, `preview`). They are easily configurable locally (such as in a `.dev.vars` file or directly in Wrangler configuration). +- [**Environment Variables (`vars`)**](/workers/wrangler/configuration/#environment-variables): Environment variables are intended to be distinct between local development and deployed environments. They are easily configurable locally (such as in a `.dev.vars` file or directly in Wrangler configuration). - [**Secrets**](/workers/wrangler/configuration/#secrets): Like environment variables, secrets are expected to have different values in local development versus deployed environments for security reasons. Use `.dev.vars` for local secret management. @@ -316,46 +311,138 @@ If you have use-cases for connecting to any of the remote resources above, pleas - **Network latency**: Expect network latency for operations on these remotely connected bindings, as they involve communication over the internet. -- **Environment Variables & Secrets**: Standard environment variables (from `vars`) and Secrets always use their locally defined values during local development. The `experimental_remote: true` flag does not apply to them. - ### API -TO-DO +Wrangler provides programmatic utilities to help tooling authors support remote binding connections when running Workers code with [Miniflare](/workers/testing/miniflare/). + +**Key APIs include:** + +- [`experimental_startRemoteProxySession`](#experimental_startRemoteProxySession): Starts a proxy session that allows interaction with remote bindings. +- [`unstable_convertConfigBindingsToStartWorkerBindings`](#unstable_convertconfigbindingstostartworkerbindings): Utility for converting binding definitions. +- [`experimental_maybeStartOrUpdateProxySession`](#experimental_maybestartorupdatemixedmodesession): Convenience function to easily start or update a proxy session. + +#### `experimental_startRemoteProxySession` + +This function starts a proxy session for a given set of bindings. It accepts options to control session behavior, including an `auth` option with your Cloudflare account ID and API token for remote binding access. -## Remote development (Legacy) +It returns an object with: + +- `ready` : Resolves when the session is ready. +- `dispose` : Stops the session. +- `updateBindings` : Updates session bindings. +- `remoteProxyConnectionString` : String to pass to Miniflare for remote binding access. + +#### `unstable_convertConfigBindingsToStartWorkerBindings` + +The `unstable_readConfig` utility returns an `Unstable_Config` object which includes the definition of the bindings included in the configuration file. These bindings definitions +are however not directly compatible with `experimental_startRemoteProxySession`. It can be quite convenient to however read the binding declarations with `unstable_readConfig` and then +pass them to `experimental_startRemoteProxySession`, so for this wrangler exposes `unstable_convertConfigBindingsToStartWorkerBindings` which is a simple utility to convert +the bindings in an `Unstable_Config` object into a structure that can be passed to `experimental_startRemoteProxySession`. + + + +#### `experimental_maybeStartOrUpdateRemoteProxySession` + +This wrapper simplifies proxy session management. It takes: + +- The path to your Wrangler config, or an object with remote bindings. +- The current proxy session details (or `null` if none). + +It returns: + +- `null` if no proxy session is needed. +- An object with the proxy session details if started or updated. + +The function: + +- Based on the first argument prepares the input arguments for the proxy session. +- If there are no remote bindings to be used (nor a pre-existing proxy session) it returns null, signaling that no proxy session is needed. +- If the details of an existing proxy session have been provided it updates the proxy session accordingly. +- Otherwise if starts a new proxy session. +- Returns the proxy session details (that can later be passed as the second argument to `experimental_maybeStartOrUpdateRemoteProxySession`). + +#### Example + +Here's a basic example of using Miniflare with `experimental_maybeStartOrUpdateRemoteProxySession` to provide a local dev session with remote bindings. This example uses a single hardcoded KV binding. + + +```ts +import { Miniflare, MiniflareOptions } from "miniflare"; +import { experimental_maybeStartOrUpdateRemoteProxySession } from "wrangler"; + +let mf: Miniflare | null; + +let remoteProxySessionDetails: Awaited< +ReturnType + +> | null = null; + +async function startOrUpdateDevSession() { +remoteProxySessionDetails = +await experimental_maybeStartOrUpdateRemoteProxySession( +{ +bindings: { +MY_KV: { +type: 'kv_namespace', +id: 'kv-id', +experimental_remote: true, +} +} +}, +remoteProxySessionDetails +); + +const miniflareOptions: MiniflareOptions = { +scriptPath: "./worker.js", +kvNamespaces: { +MY_KV: { +id: "kv-id", +remoteProxyConnectionString: +remoteProxySessionDetails?.session.remoteProxyConnectionString, +}, +}, +}; + +if (!mf) { +mf = new Miniflare(miniflareOptions); +} else { +mf.setOptions(miniflareOptions); +} +} + +// ... tool logic that invokes `startOrUpdateDevSession()` ... + +// ... once the dev session is no longer needed run +// `remoteProxySessionDetails?.session.dispose()` + +``` + + + +## `wrangler dev --remote` (Legacy) Separate from Miniflare-powered local development, Wrangler also offers a fully remote development mode via [`wrangler dev --remote`](/workers/wrangler/commands/#dev). Remote development is [**not** supported in the Vite plugin](/workers/local-development/wrangler-vs-vite/). -### Worker execution - During **remote development**, all of your Worker code is uploaded to a temporary preview environment on Cloudflare's infrastructure, and changes to your code are automatically uploaded as you save. -### Bindings - -When using remote development, all bindings automatically connect to their remote resources. Unlike local and hybrid development modes, you cannot configure bindings to use local simulations - they will always use the deployed resources on Cloudflare's network. +When using remote development, all bindings automatically connect to their remote resources. Unlike local development, you cannot configure bindings to use local simulations - they will always use the deployed resources on Cloudflare's network. ### When to use Remote development -- For most development tasks, the most efficient and productive experience will be local development along with [hybrid development](/workers/development-testing/#hybrid-development) when needed. +- For most development tasks, the most efficient and productive experience will be local development along with [remote bindings](/workers/development-testing/#remote-bindings) when needed. - You may want to use `wrangler dev --remote` for testing features or behaviors that are highly specific to Cloudflare's network and cannot be adequately simulated locally or tested via remote bindings. ### Considerations - Iteration is significantly slower than local development due to the upload/deployment step for each change. -### Isolating from Production - -To protect production data, you can specify preview resources in your [Wrangler configuration](/workers/wrangler/configuration/), such as: - -- [Preview namespaces for KV stores](/workers/wrangler/configuration/#kv-namespaces):`preview_id`. - - This option is **required** when using `wrangler dev --remote`. -- [Preview buckets for R2 storage](/workers/wrangler/configuration/#r2-buckets): `preview_bucket_name`. -- [Preview database IDs for D1](/workers/wrangler/configuration/#d1-databases): `preview_database_id` - -This separation ensures your development activities don't impact production data while still providing a realistic testing environment. - ### Limitations - When you run a remote development session using the `--remote` flag, a limit of 50 [routes](/workers/configuration/routing/routes/) per zone is enforced. Learn more in[ Workers platform limits](/workers/platform/limits/#number-of-routes-per-zone-when-using-wrangler-dev---remote). +``` diff --git a/src/content/partials/workers/bindings_per_env.mdx b/src/content/partials/workers/bindings_per_env.mdx index 8dbb51887867c2..3443ff41fdb87d 100644 --- a/src/content/partials/workers/bindings_per_env.mdx +++ b/src/content/partials/workers/bindings_per_env.mdx @@ -2,42 +2,64 @@ {} --- -The three development modes differ in [**where your Worker executes** and **how bindings connect**](/workers/development-testing/#core-concepts): +## Local development -**Local Development:** [Worker execution](/workers/development-testing/#worker-execution) runs locally on your machine. [Bindings](/workers/development-testing/#bindings) connect to local resource simulations. Supported in both [`wrangler dev`](/workers/wrangler/commands/#dev) and the [Cloudflare Vite plugin](/workers/vite-plugin/). +During local development, your Worker code always executes locally and bindings connect to locally simulated resources [by default](/workers/development-testing/#remote-bindings). -**Hybrid Development:** [Worker execution](/workers/development-testing/#worker-execution-1) runs locally on your machine. [Bindings](/workers/development-testing/#bindings-1) can connect to local simulations (default) or remote resources via `experimental_remote: true` configuration. Supported in both [`wrangler dev --x-hybrid-dev`](/workers/development-testing/#hybrid-development) and the Cloudflare Vite plugin. +You can configure [**remote bindings** during local development](/workers/development-testing/#remote-bindings), allowing your bindings to connect to a deployed resource on a per-binding basis. -**Remote Development:** [Worker execution](/workers/development-testing/#worker-execution-2) runs on Cloudflare's infrastructure. [Bindings](/workers/development-testing/#bindings-2) always connect to remote resources. Supported only in [`wrangler dev --remote`](/workers/wrangler/commands/#dev) - there is **no Vite plugin equivalent**. +| Binding | Local simulations | Remote binding connections | +| --------------------------------------- | :---------------: | :-------------------------------------------------------------------: | +| **AI** | ❌ | ✅ [**Recommended**](/workers/development-testing/#workers-ai) | +| **Assets** | ✅ | ❌ | +| **Analytics Engine** | ✅[^4] | ❌ | +| **Browser Rendering** | ❌ | ✅ [**Recommended**](/workers/development-testing/#browser-rendering) | +| **D1** | ✅ | ✅ | +| **Durable Objects** | ✅ | ❌ | +| **Email Bindings** | ✅ | ✅ | +| **Hyperdrive** | ✅[^2] | ❌ | +| **Images** | ✅ | ✅ [**Recommended**](/workers/development-testing/#images) | +| **KV** | ✅ | ✅ | +| **mTLS** | ❌ | ✅ [**Recommended**](/workers/development-testing/#mtls) | +| **Queues** | ✅ | ✅ | +| **R2** | ✅ | ✅ | +| **Rate Limiting** | ✅ | ❌ | +| **Service Bindings (multiple Workers)** | ✅ | ✅ | +| **Vectorize** | ❌ | ✅ [**Recommended**](/workers/development-testing/#vectorize) | +| **Workflows** | ✅ | ✅ | -| Binding | Local dev | Hybrid dev | Remote dev | -| --------------------------------------- | :-------: | :--------: | :--------: | -| **AI** | ✅[^1] | ✅ [**Recommended**](/workers/development-testing/#workers-ai) | ✅ | -| **Assets** | ✅ | ❌ | ✅ | -| **Analytics Engine** | ✅[^4] | ❌ | ✅ | -| **Browser Rendering** | ❌ | ✅ [**Recommended**](/workers/development-testing/#browser-rendering) | ✅ | -| **D1** | ✅ | ✅ | ✅ | -| **Durable Objects** | ✅ | ❌ | ✅ | -| **Email Bindings** | ✅ | ✅ | ✅ | -| **Hyperdrive** | ✅[^2] | ❌ | ✅ | -| **Images** | ✅ | ✅ [**Recommended**](/workers/development-testing/#images) | ✅ | -| **KV** | ✅ | ✅ | ✅ | -| **mTLS** | ❌ | ✅ [**Recommended**](/workers/development-testing/#mtls) | ✅ | -| **Queues** | ✅ | ✅ | ❌ | -| **R2** | ✅ | ✅ | ✅ | -| **Rate Limiting** | ✅ | ❌ | ✅ | -| **Service Bindings (multiple Workers)** | ✅ | ✅ | ✅ | -| **Vectorize** | ✅[^3] | ✅ [**Recommended**](/workers/development-testing/#vectorize) | ✅ | -| **Workflows** | ✅ | ✅ | ❌ | +- **Local simulations:** Bindings connect to local resource simulations. Supported in [`wrangler dev`](/workers/wrangler/commands/#dev) and the [Cloudflare Vite plugin](/workers/vite-plugin/). -[^1]: Using Workers AI always accesses your Cloudflare account in order to run AI models and will incur usage charges, even in local development. +- **Remote binding connections:** Bindings connect to remote resources via `experimental_remote: true` configuration. Supported in [`wrangler dev --x-remote-bindings`](/workers/development-testing/#using-wrangler-with-remote-bindings) and the [Cloudflare Vite plugin](/workers/development-testing/#using-vite-with-remote-bindings). -[^2]: Using Hyperdrive with local development allows you to connect to a local database (running on `localhost`) but you cannot connect to a remote database. To connect to a remote database, use `wrangler dev --remote`. +## Remote development -[^3]: Using Vectorize always accesses your Cloudflare account to run queries, and will incur usage charges even in local development. +During remote development, all of your Worker code is uploaded and executed on Cloudflare's infrastructure, and bindings always connect to remote resources. **We recommend using local development with remote binding connections instead** for faster iteration and debugging. -[^4]: Analytics Engine is supported in local development with Wrangler but is not currently supported in the Vite plugin. +Supported only in [`wrangler dev --remote`](/workers/wrangler/commands/#dev) - there is **no Vite plugin equivalent**. -> **Tip:** If you have a binding with no local dev support, try [hybrid development](/workers/development-testing/#hybrid-development) to connect to the remote resource while keeping your Worker code running locally. +| Binding | Remote development | +| --------------------------------------- | :----------------: | +| **AI** | ✅ | +| **Assets** | ✅ | +| **Analytics Engine** | ✅ | +| **Browser Rendering** | ✅ | +| **D1** | ✅ | +| **Durable Objects** | ✅ | +| **Email Bindings** | ✅ | +| **Hyperdrive** | ✅ | +| **Images** | ✅ | +| **KV** | ✅ | +| **mTLS** | ✅ | +| **Queues** | ❌ | +| **R2** | ✅ | +| **Rate Limiting** | ✅ | +| **Service Bindings (multiple Workers)** | ✅ | +| **Vectorize** | ✅ | +| **Workflows** | ❌ | ---- \ No newline at end of file +[^2]: Using Hyperdrive with local simulations allows you to connect to a local database (running on `localhost`) but you cannot connect to a remote database. To connect to a remote database, use `wrangler dev --remote`. + +[^4]: Analytics Engine is supported with local simulations in Wrangler but is not currently supported in the Vite plugin. + +--- From 4d97c43e1809e28a27bf42c2a381c2a050463830 Mon Sep 17 00:00:00 2001 From: korinne Date: Tue, 17 Jun 2025 16:49:10 -0700 Subject: [PATCH 06/12] updates workers for platforms with remote bindings information --- .../get-started/developing-with-wrangler.mdx | 22 +++++++++++++++++ .../docs/d1/observability/debug-d1.mdx | 2 +- .../reference/environments.mdx | 2 +- src/content/docs/pages/functions/bindings.mdx | 4 ++-- .../functions/wrangler-configuration.mdx | 6 ++--- .../workers/development-testing/index.mdx | 24 +++++++++++++++++-- .../development-testing/local-data.mdx | 2 +- .../docs/workers/get-started/dashboard.mdx | 2 +- .../observability/dev-tools/breakpoints.mdx | 2 +- .../observability/dev-tools/cpu-usage.mdx | 2 +- .../workers/observability/dev-tools/index.mdx | 2 +- .../observability/dev-tools/memory-usage.mdx | 2 +- .../observability/logs/real-time-logs.mdx | 2 +- .../observability/logs/tail-workers.mdx | 2 +- src/content/docs/workers/platform/limits.mdx | 2 +- .../migration-guides/migrate-from-pages.mdx | 2 +- .../reference/migrating-from-wrangler-dev.mdx | 2 +- .../docs/workers/wrangler/commands.mdx | 4 ++-- .../docs/workers/wrangler/configuration.mdx | 6 ++--- 19 files changed, 67 insertions(+), 25 deletions(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx index 2160adc63c0a79..c16cf2b1e04833 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx @@ -199,3 +199,25 @@ curl http://localhost:8600 ```sh output # -> user worker got "intercepted a request for customer-1 by the outbound" from fetch ``` + +## Remote dispatch namespaces + +You can configure dispatch namespace bindings to connect to remote dispatch namespaces during local development by setting `experimental_remote = true`: + + +```jsonc title="wrangler.jsonc" +{ + "dispatch_namespaces": [ + { + "binding": "DISPATCH_NAMESPACE", + "namespace": "testing", + "experimental_remote":true + } + ] +} +``` + + +This allows you to run your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) locally, while connecting it to your remote dispatch namespace binding. This allows you to test changes to your core dispatching logic against real, deployed [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers). + +For more information about remote bindings during local development, refer to [remote binding documentation](/workers/development-testing/#remote-bindings). diff --git a/src/content/docs/d1/observability/debug-d1.mdx b/src/content/docs/d1/observability/debug-d1.mdx index afcb4b9ae3ff24..098f55ee12306a 100644 --- a/src/content/docs/d1/observability/debug-d1.mdx +++ b/src/content/docs/d1/observability/debug-d1.mdx @@ -94,4 +94,4 @@ You should include as much of the following in any bug report: * Learn [how to debug Workers](/workers/observability/). * Understand how to [access logs](/workers/observability/logs/) generated from your Worker and D1. -* Use [`wrangler dev`](/workers/wrangler/commands/#dev) to run your Worker and D1 locally and [debug issues before deploying](/workers/local-development/). +* Use [`wrangler dev`](/workers/wrangler/commands/#dev) to run your Worker and D1 locally and [debug issues before deploying](/workers/development-testing/). diff --git a/src/content/docs/durable-objects/reference/environments.mdx b/src/content/docs/durable-objects/reference/environments.mdx index 3a1d92974aca6e..e8fffc8a79d3f1 100644 --- a/src/content/docs/durable-objects/reference/environments.mdx +++ b/src/content/docs/durable-objects/reference/environments.mdx @@ -73,7 +73,7 @@ Local development sessions create a standalone, local-only environment that mirr An existing Durable Object binding of `DB` would be available to your Worker when running locally. -Refer to Workers [Local development](/workers/local-development/#supported-resource-bindings-in-different-environments). +Refer to Workers [Local development](/workers/development-testing/bindings-per-env/). ## Remote development diff --git a/src/content/docs/pages/functions/bindings.mdx b/src/content/docs/pages/functions/bindings.mdx index b6f11dce96b19c..2024ad1ab49daa 100644 --- a/src/content/docs/pages/functions/bindings.mdx +++ b/src/content/docs/pages/functions/bindings.mdx @@ -201,7 +201,7 @@ You can interact with your R2 bucket bindings locally in one of two ways: :::note -By default, Wrangler automatically persists data to local storage. For more information, refer to [Local development](/workers/local-development/). +By default, Wrangler automatically persists data to local storage. For more information, refer to [Local development](/workers/development-testing/). ::: @@ -282,7 +282,7 @@ Interact with this binding by using `context.env` (for example, `context.env.NOR :::note -By default, Wrangler automatically persists data to local storage. For more information, refer to [Local development](/workers/local-development/). +By default, Wrangler automatically persists data to local storage. For more information, refer to [Local development](/workers/development-testing/). ::: diff --git a/src/content/docs/pages/functions/wrangler-configuration.mdx b/src/content/docs/pages/functions/wrangler-configuration.mdx index 9c07dd8659d237..82977ce8d74829 100644 --- a/src/content/docs/pages/functions/wrangler-configuration.mdx +++ b/src/content/docs/pages/functions/wrangler-configuration.mdx @@ -433,7 +433,7 @@ A [binding](/pages/functions/bindings/) enables your Pages Functions to interact :::note -When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production database. Refer to [Local development](/workers/local-development/) for more details. +When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production database. Refer to [Local development](/workers/development-testing/) for more details. ::: @@ -475,7 +475,7 @@ Workers, the `script_name` key is optional. :::note -When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production namespace. Refer to [Local development](/workers/local-development/) for more details. +When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production namespace. Refer to [Local development](/workers/development-testing/) for more details. ::: @@ -501,7 +501,7 @@ You cannot currently configure a [queues consumer](/queues/reference/how-queues- :::note -When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production bucket. Refer to [Local development](/workers/local-development/) for more details. +When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production bucket. Refer to [Local development](/workers/development-testing/) for more details. ::: diff --git a/src/content/docs/workers/development-testing/index.mdx b/src/content/docs/workers/development-testing/index.mdx index 46de51d9a2906d..bd97ff5ca4c582 100644 --- a/src/content/docs/workers/development-testing/index.mdx +++ b/src/content/docs/workers/development-testing/index.mdx @@ -23,7 +23,7 @@ import { You can build, run, and test your Worker code on your own local machine before deploying it to Cloudflare's network. This is made possible through [Miniflare](/workers/testing/miniflare/), a simulator that executes your Worker code using the same runtime used in production, [`workerd`](https://github.com/cloudflare/workerd). -By default, your Worker's bindings connect to locally simulated resources, but can be configured to interact with the real, production resource. +[By default](/workers/development-testing/#defaults), your Worker's bindings [connect to locally simulated resources](/workers/development-testing/#bindings-during-local-development), but can be configured to interact with the real, production resource with [remote bindings](/workers/development-testing/#remote-bindings). ## Core concepts @@ -276,6 +276,26 @@ If a Workers AI binding has `experimental_remote` set to `false`, Cloudflare wil +#### [Dispatch Namespaces](/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler/): + +Workers for Platforms users can configure `experimental_remote: true` in dispatch namespace binding definitions: + + +```jsonc title="wrangler.jsonc" +{ + "dispatch_namespaces": [ + { + "binding": "DISPATCH_NAMESPACE", + "namespace": "testing", + "experimental_remote":true + } + ] +} +``` + + +This allows you to run your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) locally, while connecting it to your remote dispatch namespace binding. This allows you to test changes to your core dispatching logic against real, deployed [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers). + ### Unsupported remote bindings Certain bindings are not supported for remote connections during local development (`experimental_remote: true`). These will always use local simulations or local values. @@ -425,7 +445,7 @@ mf.setOptions(miniflareOptions); ## `wrangler dev --remote` (Legacy) -Separate from Miniflare-powered local development, Wrangler also offers a fully remote development mode via [`wrangler dev --remote`](/workers/wrangler/commands/#dev). Remote development is [**not** supported in the Vite plugin](/workers/local-development/wrangler-vs-vite/). +Separate from Miniflare-powered local development, Wrangler also offers a fully remote development mode via [`wrangler dev --remote`](/workers/wrangler/commands/#dev). Remote development is [**not** supported in the Vite plugin](/workers/development-testing/wrangler-vs-vite/). diff --git a/src/content/docs/workers/development-testing/local-data.mdx b/src/content/docs/workers/development-testing/local-data.mdx index 187b96922437ee..233d68638a7c17 100644 --- a/src/content/docs/workers/development-testing/local-data.mdx +++ b/src/content/docs/workers/development-testing/local-data.mdx @@ -16,7 +16,7 @@ import { Aside, } from "~/components"; -Whether you are using Wrangler or the [Cloudflare Vite plugin](https://developers.cloudflare.com/workers/vite-plugin/), your workflow for **accessing** data during local development remains the same. However, you can only [populate local resources with data](/workers/local-development/local-data/#populating-local-resources-with-data) via the Wrangler CLI. +Whether you are using Wrangler or the [Cloudflare Vite plugin](https://developers.cloudflare.com/workers/vite-plugin/), your workflow for **accessing** data during local development remains the same. However, you can only [populate local resources with data](/workers/development-testing/local-data/#populating-local-resources-with-data) via the Wrangler CLI. ### How it works diff --git a/src/content/docs/workers/get-started/dashboard.mdx b/src/content/docs/workers/get-started/dashboard.mdx index e0430806f448ab..ba2cdd65366ff4 100644 --- a/src/content/docs/workers/get-started/dashboard.mdx +++ b/src/content/docs/workers/get-started/dashboard.mdx @@ -42,7 +42,7 @@ git clone cd ``` -Now, you can preview and test your changes by [running Wrangler in your local development environment](/workers/local-development/). Once you are ready to deploy you can run: +Now, you can preview and test your changes by [running Wrangler in your local development environment](/workers/development-testing/). Once you are ready to deploy you can run: ```bash # adds the files to git tracking diff --git a/src/content/docs/workers/observability/dev-tools/breakpoints.mdx b/src/content/docs/workers/observability/dev-tools/breakpoints.mdx index 54c7d8c13dc20e..f5d9bd4e218206 100644 --- a/src/content/docs/workers/observability/dev-tools/breakpoints.mdx +++ b/src/content/docs/workers/observability/dev-tools/breakpoints.mdx @@ -62,4 +62,4 @@ The `.vscode/launch.json` file only applies to a single workspace. If you prefer ## Related resources -- [Local Development](/workers/local-development/) - Develop your Workers and connected resources locally via Wrangler and [`workerd`](https://github.com/cloudflare/workerd), for a fast, accurate feedback loop. +- [Local Development](/workers/development-testing/) - Develop your Workers and connected resources locally via Wrangler and [`workerd`](https://github.com/cloudflare/workerd), for a fast, accurate feedback loop. diff --git a/src/content/docs/workers/observability/dev-tools/cpu-usage.mdx b/src/content/docs/workers/observability/dev-tools/cpu-usage.mdx index 3c9bf5749df8dd..5dac8961ef6d6d 100644 --- a/src/content/docs/workers/observability/dev-tools/cpu-usage.mdx +++ b/src/content/docs/workers/observability/dev-tools/cpu-usage.mdx @@ -17,7 +17,7 @@ for security purposes. However, measuring CPU execution times is possible in loc When using DevTools to monitor CPU usage, it may be difficult to replicate specific behavior you are seeing in production. To mimic production behavior, make sure the requests you send to the local Worker are similar to requests in production. This might mean sending a large volume of requests, making requests -to specific routes, or using production-like data with the [--remote flag](/workers/local-development/#develop-using-remote-resources-and-bindings). +to specific routes, or using production-like data with the [--remote flag](/workers/development-testing/#remote-bindings). ## Taking a profile diff --git a/src/content/docs/workers/observability/dev-tools/index.mdx b/src/content/docs/workers/observability/dev-tools/index.mdx index f451ad70b9492a..43dc82afaa56ca 100644 --- a/src/content/docs/workers/observability/dev-tools/index.mdx +++ b/src/content/docs/workers/observability/dev-tools/index.mdx @@ -31,4 +31,4 @@ DevTools can be used in a variety of situations. For more information, see the d ## Related resources -- [Local development](/workers/local-development/) - Develop your Workers and connected resources locally via Wrangler and workerd, for a fast, accurate feedback loop. +- [Local development](/workers/development-testing/) - Develop your Workers and connected resources locally via Wrangler and workerd, for a fast, accurate feedback loop. diff --git a/src/content/docs/workers/observability/dev-tools/memory-usage.mdx b/src/content/docs/workers/observability/dev-tools/memory-usage.mdx index 8ef523e8e5b62c..1146fbbd7692f9 100644 --- a/src/content/docs/workers/observability/dev-tools/memory-usage.mdx +++ b/src/content/docs/workers/observability/dev-tools/memory-usage.mdx @@ -16,7 +16,7 @@ objects in memory. When using DevTools to profile memory, it may be difficult to replicate specific behavior you are seeing in production. To mimic production behavior, make sure the requests you send to the local Worker are similar to requests in production. This might mean sending a large volume of requests, making requests -to specific routes, or using production-like data with the [--remote flag](/workers/local-development/#develop-using-remote-resources-and-bindings). +to specific routes, or using production-like data with the [--remote flag](/workers/development-testing/#remote-bindings). ## Taking a snapshot diff --git a/src/content/docs/workers/observability/logs/real-time-logs.mdx b/src/content/docs/workers/observability/logs/real-time-logs.mdx index af8617893f1703..fd5c07c7b5545d 100644 --- a/src/content/docs/workers/observability/logs/real-time-logs.mdx +++ b/src/content/docs/workers/observability/logs/real-time-logs.mdx @@ -97,7 +97,7 @@ Logs can be persisted, filtered, and analyzed with [Workers Logs](/workers/obser ## Related resources - [Errors and exceptions](/workers/observability/errors/) - Review common Workers errors. -- [Local development and testing](/workers/local-development/) - Develop and test you Workers locally. +- [Local development and testing](/workers/development-testing/) - Develop and test you Workers locally. - [Workers Logs](/workers/observability/logs/workers-logs) - Collect, store, filter and analyze logging data emitted from Cloudflare Workers. - [Logpush](/workers/observability/logs/logpush/) - Learn how to push Workers Trace Event Logs to supported destinations. - [Tail Workers](/workers/observability/logs/tail-workers/) - Learn how to attach Tail Workers to transform your logs and send them to HTTP endpoints. diff --git a/src/content/docs/workers/observability/logs/tail-workers.mdx b/src/content/docs/workers/observability/logs/tail-workers.mdx index 7be5b7f503158a..27ec80a2a70aa6 100644 --- a/src/content/docs/workers/observability/logs/tail-workers.mdx +++ b/src/content/docs/workers/observability/logs/tail-workers.mdx @@ -105,5 +105,5 @@ The Worker that you add a `tail_consumers` binding to must have a `tail()` handl * [`tail()`](/workers/runtime-apis/handlers/tail/) Handler API docs - Learn how to set up a `tail()` handler in your Worker. - [Errors and exceptions](/workers/observability/errors/) - Review common Workers errors. -- [Local development and testing](/workers/local-development/) - Develop and test you Workers locally. +- [Local development and testing](/workers/development-testing/) - Develop and test you Workers locally. - [Source maps and stack traces](/workers/observability/source-maps) - Learn how to enable source maps and generate stack traces for Workers. diff --git a/src/content/docs/workers/platform/limits.mdx b/src/content/docs/workers/platform/limits.mdx index 6171de3669669b..a1198c6ccec925 100644 --- a/src/content/docs/workers/platform/limits.mdx +++ b/src/content/docs/workers/platform/limits.mdx @@ -326,7 +326,7 @@ Each zone has a limit of 1,000 [routes](/workers/configuration/routing/routes/). ### Number of routes per zone when using `wrangler dev --remote` -When you run a [remote development](/workers/local-development/#develop-using-remote-resources-and-bindings) session using the `--remote` flag, a limit of 50 [routes](/workers/configuration/routing/routes/) per zone is enforced. The Quick Editor in the Cloudflare Dashboard also uses `wrangler dev --remote`, so any changes made there are subject to the same 50-route limit. If your zone has more than 50 routes, you **will not be able to run a remote session**. To fix this, you must remove routes until you are under the 50-route limit. +When you run a [remote development](/workers/development-testing/#remote-bindings) session using the `--remote` flag, a limit of 50 [routes](/workers/configuration/routing/routes/) per zone is enforced. The Quick Editor in the Cloudflare Dashboard also uses `wrangler dev --remote`, so any changes made there are subject to the same 50-route limit. If your zone has more than 50 routes, you **will not be able to run a remote session**. To fix this, you must remove routes until you are under the 50-route limit. ### Number of custom domains per zone diff --git a/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx b/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx index ad7829adb40090..5aa096d0e29950 100644 --- a/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx +++ b/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx @@ -391,7 +391,7 @@ This compatibility matrix compares the features of Workers and Pages. Unless oth | [Gradual Deployments](/workers/configuration/versions-and-deployments/) | ✅ | ❌ | | [Preview URLs](/workers/configuration/previews) | ✅ | ✅ | | [Testing tools](/workers/testing) | ✅ | ✅ | -| [Local Development](/workers/local-development/) | ✅ | ✅ | +| [Local Development](/workers/development-testing/) | ✅ | ✅ | | [Remote Development (`--remote`)](/workers/wrangler/commands/) | ✅ | ❌ | | [Quick Editor in Dashboard](https://blog.cloudflare.com/improved-quick-edit) | ✅ | ❌ | | **Static Assets** | | | diff --git a/src/content/docs/workers/vite-plugin/reference/migrating-from-wrangler-dev.mdx b/src/content/docs/workers/vite-plugin/reference/migrating-from-wrangler-dev.mdx index 851391bc27c2ce..9fcbb97f63debe 100644 --- a/src/content/docs/workers/vite-plugin/reference/migrating-from-wrangler-dev.mdx +++ b/src/content/docs/workers/vite-plugin/reference/migrating-from-wrangler-dev.mdx @@ -30,5 +30,5 @@ See [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for m ## No remote mode -The Vite plugin does not support [remote mode](/workers/local-development/#develop-using-remote-resources-and-bindings). +The Vite plugin does not support [remote mode](/workers/development-testing/#remote-bindings). We will be adding support for accessing remote resources in local development in a future update. diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx index 6be45fbb871a7e..56712238d7d829 100644 --- a/src/content/docs/workers/wrangler/commands.mdx +++ b/src/content/docs/workers/wrangler/commands.mdx @@ -244,7 +244,7 @@ None of the options for this command are required. Many of these options can be -`wrangler dev` is a way to [locally test](/workers/local-development/) your Worker while developing. With `wrangler dev` running, send HTTP requests to `localhost:8787` and your Worker should execute as expected. You will also see `console.log` messages and exceptions appearing in your terminal. +`wrangler dev` is a way to [locally test](/workers/development-testing/) your Worker while developing. With `wrangler dev` running, send HTTP requests to `localhost:8787` and your Worker should execute as expected. You will also see `console.log` messages and exceptions appearing in your terminal. --- @@ -491,7 +491,7 @@ Finished processing secrets JSON file: With the release of [Secrets Store](/secrets-store/) in open beta, you can use the following commands to manage your account secrets. :::note[`--remote` option] -In order to interact with Secrets Store in production, you should append `--remote` to your command. Without it, your command will default to [local development mode](/workers/local-development/). +In order to interact with Secrets Store in production, you should append `--remote` to your command. Without it, your command will default to [local development mode](/workers/development-testing/). ::: ### `create` diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 98f1e51ef36e6c..4fc5419f76592c 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -504,7 +504,7 @@ To bind D1 databases to your Worker, assign an array of the below object to the :::note -When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production database. Refer to [Local development and testing](/workers/local-development/) for more details. +When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production database. Refer to [Local development and testing](/workers/development-testing/) for more details. ::: @@ -721,7 +721,7 @@ To bind KV namespaces to your Worker, assign an array of the below object to the :::note -When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production namespace. Refer to [Local development and testing](/workers/local-development/) for more details. +When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production namespace. Refer to [Local development and testing](/workers/development-testing/) for more details. ::: @@ -846,7 +846,7 @@ To bind R2 buckets to your Worker, assign an array of the below object to the `r :::note -When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production bucket. Refer to [Local development and testing](/workers/local-development/) for more details. +When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production bucket. Refer to [Local development and testing](/workers/development-testing/) for more details. ::: From f6de38a3abda3fb81cf577118a71341806334193 Mon Sep 17 00:00:00 2001 From: korinne Date: Wed, 18 Jun 2025 07:53:24 -0700 Subject: [PATCH 07/12] updates example config --- src/content/docs/workers/development-testing/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/development-testing/index.mdx b/src/content/docs/workers/development-testing/index.mdx index bd97ff5ca4c582..2880c5c7bd9ccc 100644 --- a/src/content/docs/workers/development-testing/index.mdx +++ b/src/content/docs/workers/development-testing/index.mdx @@ -79,7 +79,7 @@ During local development, your Worker code interacts with these bindings using t ```jsonc title="wrangler.jsonc" { "name": "my-worker", - "compatibility_date": "2025-06-01", + "compatibility_date": "$today", "r2_buckets": [ { @@ -157,7 +157,7 @@ If preview configuration is present for a binding, setting `experimental_remote: ```jsonc title="wrangler.jsonc" { "name": "my-worker", - "compatibility_date": "2025-06-01", + "compatibility_date": "$today", "r2_buckets": [ { From 16ba2a90317e445f5705d0c1eb5f2a092f6f0bc1 Mon Sep 17 00:00:00 2001 From: korinne <40270578+korinne@users.noreply.github.com> Date: Wed, 18 Jun 2025 08:07:20 -0700 Subject: [PATCH 08/12] Update src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx Co-authored-by: Dario Piotrowicz --- .../get-started/developing-with-wrangler.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx index c16cf2b1e04833..91803b6492da13 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx @@ -211,7 +211,7 @@ You can configure dispatch namespace bindings to connect to remote dispatch name { "binding": "DISPATCH_NAMESPACE", "namespace": "testing", - "experimental_remote":true + "experimental_remote": true } ] } From faebe50141a1c0d13c3f1b0980b62d402839c4df Mon Sep 17 00:00:00 2001 From: korinne <40270578+korinne@users.noreply.github.com> Date: Wed, 18 Jun 2025 08:07:32 -0700 Subject: [PATCH 09/12] Update src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx Co-authored-by: Dario Piotrowicz --- .../get-started/developing-with-wrangler.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx index 91803b6492da13..0129ef93617a64 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx @@ -220,4 +220,4 @@ You can configure dispatch namespace bindings to connect to remote dispatch name This allows you to run your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) locally, while connecting it to your remote dispatch namespace binding. This allows you to test changes to your core dispatching logic against real, deployed [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers). -For more information about remote bindings during local development, refer to [remote binding documentation](/workers/development-testing/#remote-bindings). +For more information about remote bindings during local development, refer to [remote bindings documentation](/workers/development-testing/#remote-bindings). From 75426ea391741f4852be06938bd351ad1c399e5b Mon Sep 17 00:00:00 2001 From: korinne Date: Wed, 18 Jun 2025 08:27:09 -0700 Subject: [PATCH 10/12] updates bindings comparison, small changes to wording --- .../get-started/developing-with-wrangler.mdx | 4 +- .../partials/workers/bindings_per_env.mdx | 42 +++++++++---------- 2 files changed, 21 insertions(+), 25 deletions(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx index 0129ef93617a64..e0f0ec8c72af37 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx @@ -202,7 +202,7 @@ curl http://localhost:8600 ## Remote dispatch namespaces -You can configure dispatch namespace bindings to connect to remote dispatch namespaces during local development by setting `experimental_remote = true`: +You can configure dispatch namespace bindings to connect to remote dispatch namespaces during local development by setting [`experimental_remote = true`](/workers/development-testing/#remote-bindings): ```jsonc title="wrangler.jsonc" @@ -218,6 +218,6 @@ You can configure dispatch namespace bindings to connect to remote dispatch name ``` -This allows you to run your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) locally, while connecting it to your remote dispatch namespace binding. This allows you to test changes to your core dispatching logic against real, deployed [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers). +This allows you to run your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) locally, while connecting it to your remote dispatch namespace binding. You can then test changes to your core dispatching logic against real, deployed [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers). For more information about remote bindings during local development, refer to [remote bindings documentation](/workers/development-testing/#remote-bindings). diff --git a/src/content/partials/workers/bindings_per_env.mdx b/src/content/partials/workers/bindings_per_env.mdx index 3443ff41fdb87d..c16ea1409ea2a8 100644 --- a/src/content/partials/workers/bindings_per_env.mdx +++ b/src/content/partials/workers/bindings_per_env.mdx @@ -8,25 +8,25 @@ During local development, your Worker code always executes locally and bindings You can configure [**remote bindings** during local development](/workers/development-testing/#remote-bindings), allowing your bindings to connect to a deployed resource on a per-binding basis. -| Binding | Local simulations | Remote binding connections | -| --------------------------------------- | :---------------: | :-------------------------------------------------------------------: | -| **AI** | ❌ | ✅ [**Recommended**](/workers/development-testing/#workers-ai) | -| **Assets** | ✅ | ❌ | -| **Analytics Engine** | ✅[^4] | ❌ | -| **Browser Rendering** | ❌ | ✅ [**Recommended**](/workers/development-testing/#browser-rendering) | -| **D1** | ✅ | ✅ | -| **Durable Objects** | ✅ | ❌ | -| **Email Bindings** | ✅ | ✅ | -| **Hyperdrive** | ✅[^2] | ❌ | -| **Images** | ✅ | ✅ [**Recommended**](/workers/development-testing/#images) | -| **KV** | ✅ | ✅ | -| **mTLS** | ❌ | ✅ [**Recommended**](/workers/development-testing/#mtls) | -| **Queues** | ✅ | ✅ | -| **R2** | ✅ | ✅ | -| **Rate Limiting** | ✅ | ❌ | -| **Service Bindings (multiple Workers)** | ✅ | ✅ | -| **Vectorize** | ❌ | ✅ [**Recommended**](/workers/development-testing/#vectorize) | -| **Workflows** | ✅ | ✅ | +| Binding | Local simulations | Remote binding connections | +| --------------------------------------- | :---------------: | :------------------------: | +| **AI** | ❌ | ✅ | +| **Assets** | ✅ | ❌ | +| **Analytics Engine** | ✅ | ❌ | +| **Browser Rendering** | ❌ | ✅ | +| **D1** | ✅ | ✅ | +| **Durable Objects** | ✅ | ❌ | +| **Email Bindings** | ✅ | ✅ | +| **Hyperdrive** | ✅ | ❌ | +| **Images** | ✅ | ✅ | +| **KV** | ✅ | ✅ | +| **mTLS** | ❌ | ✅ | +| **Queues** | ✅ | ✅ | +| **R2** | ✅ | ✅ | +| **Rate Limiting** | ✅ | ❌ | +| **Service Bindings (multiple Workers)** | ✅ | ✅ | +| **Vectorize** | ❌ | ✅ | +| **Workflows** | ✅ | ✅ | - **Local simulations:** Bindings connect to local resource simulations. Supported in [`wrangler dev`](/workers/wrangler/commands/#dev) and the [Cloudflare Vite plugin](/workers/vite-plugin/). @@ -58,8 +58,4 @@ Supported only in [`wrangler dev --remote`](/workers/wrangler/commands/#dev) - t | **Vectorize** | ✅ | | **Workflows** | ❌ | -[^2]: Using Hyperdrive with local simulations allows you to connect to a local database (running on `localhost`) but you cannot connect to a remote database. To connect to a remote database, use `wrangler dev --remote`. - -[^4]: Analytics Engine is supported with local simulations in Wrangler but is not currently supported in the Vite plugin. - --- From 520b5f282412e3496b57db051c69e793ac7b14e4 Mon Sep 17 00:00:00 2001 From: korinne Date: Wed, 18 Jun 2025 08:38:17 -0700 Subject: [PATCH 11/12] updates redirects --- public/__redirects | 1 + 1 file changed, 1 insertion(+) diff --git a/public/__redirects b/public/__redirects index 881f7070b83e58..7b4bb8839d522b 100644 --- a/public/__redirects +++ b/public/__redirects @@ -1527,6 +1527,7 @@ /workers/about/tips/debugging/ /workers/observability/ 301 /workers/testing/debugging-tools/ /workers/observability/dev-tools/ 301 /workers/testing/local-development/ /workers/local-development/ 301 +/workers/local-development/ /workers/development-testing/ 301 /workers/about/using-cache/ /workers/reference/how-the-cache-works/ 301 /workers/learning/how-the-cache-works/ /workers/reference/how-the-cache-works/ 301 /workers/api/ /api/resources/workers/subresources/scripts/methods/list/ 301 From 4cd35739c211c34bbda6079c372935ca8e3a7655 Mon Sep 17 00:00:00 2001 From: korinne Date: Wed, 18 Jun 2025 09:49:12 -0700 Subject: [PATCH 12/12] updates more redirects --- public/__redirects | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/public/__redirects b/public/__redirects index 7b4bb8839d522b..a76d281e61734d 100644 --- a/public/__redirects +++ b/public/__redirects @@ -1527,7 +1527,11 @@ /workers/about/tips/debugging/ /workers/observability/ 301 /workers/testing/debugging-tools/ /workers/observability/dev-tools/ 301 /workers/testing/local-development/ /workers/local-development/ 301 -/workers/local-development/ /workers/development-testing/ 301 +/workers/local-development/ /workers/development-testing/#local-development 301 +/workers/local-development/bindings-per-env/ /workers/development-testing/bindings-per-env/ 301 +/workers/local-development/environment-variables/ /workers/development-testing/environment-variables/ 301 +/workers/local-development/local-data/ /workers/development-testing/local-data/ 301 +/workers/local-development/remote-data/ /workers/development-testing/#remote-bindings 301 /workers/about/using-cache/ /workers/reference/how-the-cache-works/ 301 /workers/learning/how-the-cache-works/ /workers/reference/how-the-cache-works/ 301 /workers/api/ /api/resources/workers/subresources/scripts/methods/list/ 301