diff --git a/public/__redirects b/public/__redirects index 881f7070b83e58..a76d281e61734d 100644 --- a/public/__redirects +++ b/public/__redirects @@ -1527,6 +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/#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 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..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 @@ -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`](/workers/development-testing/#remote-bindings): + + +```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. 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/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/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..2880c5c7bd9ccc --- /dev/null +++ b/src/content/docs/workers/development-testing/index.mdx @@ -0,0 +1,468 @@ +--- +pcx_content_type: navigation +title: Development & testing +sidebar: + order: 6 +head: [] +description: Develop and test your Workers locally. +--- + +import { + Details, + LinkCard, + Render, + PackageManagers, + WranglerConfig, + Aside, + InlineBadge, + CardGrid, + Card, + Type, + TypeScriptExample, +} from "~/components"; + +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](/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 + +### 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**](/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 + +**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/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/) + +### Defaults + +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. These local resources are initially empty, but you can populate them with data, as documented in [Adding local data](/workers/development-testing/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. + +## Remote bindings + +**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 + + + +```jsonc title="wrangler.jsonc" +{ + "name": "my-worker", + "compatibility_date": "$today", + + "r2_buckets": [ + { + "bucket_name": "screenshots-bucket", + "binding": "screenshots_bucket", + "experimental_remote": true, + }, + ], +} +``` + + + +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: + + + +### Using Vite with remote 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`): + +```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 }, + }), + ], +}); +``` + +### 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: + +- [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 ensure that remote bindings connect to that designated remote preview resource. + +**For example:** + + + +```jsonc title="wrangler.jsonc" +{ + "name": "my-worker", + "compatibility_date": "$today", + + "r2_buckets": [ + { + "bucket_name": "screenshots-bucket", + "binding": "screenshots_bucket", + "preview_bucket_name": "preview-screenshots-bucket", + "experimental_remote": true, + }, + ], +} +``` + + + +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`. + +### 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 + } +} +```` + + + + + +#### [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. + +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): 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. 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. + +### API + +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. + +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/development-testing/wrangler-vs-vite/). + + + +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. + +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 [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. + +### 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 96% rename from src/content/docs/workers/local-development/local-data.mdx rename to src/content/docs/workers/development-testing/local-data.mdx index 5a3b20a8022280..233d68638a7c17 100644 --- a/src/content/docs/workers/local-development/local-data.mdx +++ b/src/content/docs/workers/development-testing/local-data.mdx @@ -1,10 +1,10 @@ --- pcx_content_type: navigation -title: Local data +title: Adding local data sidebar: - order: 2 + order: 4 head: [] -description: Working with data during local development +description: Populating local resources with data --- import { @@ -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/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/index.mdx b/src/content/docs/workers/development-testing/wrangler-vs-vite.mdx similarity index 63% rename from src/content/docs/workers/local-development/index.mdx rename to src/content/docs/workers/development-testing/wrangler-vs-vite.mdx index c354b6110cb114..734a453280ee1e 100644 --- a/src/content/docs/workers/local-development/index.mdx +++ b/src/content/docs/workers/development-testing/wrangler-vs-vite.mdx @@ -1,26 +1,17 @@ --- pcx_content_type: navigation -title: Local development +title: Choosing between Wrangler & Vite sidebar: - order: 6 + order: 3 head: [] -description: Develop your Workers locally. +description: Choosing between Wrangler and Vite for local development --- -import { Details, LinkCard, Render, PackageManagers } from "~/components"; - -When building projects on Cloudflare Workers, you have two options for local development: - -- [**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/). - -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. - -## Choosing between Wrangler or Vite +# 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 +## When to use Wrangler - **Backend & Workers-focused:** If you're primarily building APIs, serverless functions, or background tasks, use Wrangler. @@ -31,7 +22,7 @@ Deciding between Wrangler and the Cloudflare Vite plugin depends on your project - **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 +## When to use the Cloudflare Vite Plugin Use the [Vite plugin](/workers/vite-plugin/) for: 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/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/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. ::: diff --git a/src/content/partials/workers/bindings_per_env.mdx b/src/content/partials/workers/bindings_per_env.mdx index d5ef6c12a097a9..c16ea1409ea2a8 100644 --- a/src/content/partials/workers/bindings_per_env.mdx +++ b/src/content/partials/workers/bindings_per_env.mdx @@ -2,44 +2,60 @@ {} --- -**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** | ✅ | ❌ | - -[^1]: Using Workers AI always accesses your Cloudflare account in order to run AI models and will incur usage charges, even in local development. - -[^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`. - -[^3]: Using Vectorize always accesses your Cloudflare account to run queries, and will incur usage charges even in local development. - -[^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. +## Local development + +During local development, your Worker code always executes locally and bindings connect to locally simulated resources [by default](/workers/development-testing/#remote-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** | ❌ | ✅ | +| **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/). + +- **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). + +## Remote 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. + +Supported only in [`wrangler dev --remote`](/workers/wrangler/commands/#dev) - there is **no Vite plugin equivalent**. + +| 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** | ❌ | ---