generally recommend using remote bindings over --remote (cloudflare#25256)

dario-piotrowicz · penalosa · caley-b · web-flow · commit 824f50ff236a · 2025-09-18T17:01:54.000-05:00
* generally recommend using remote bindings over `--remote`

* Apply suggestions from code review

Co-authored-by: Somhairle MacLeòid &lt;smacleod@cloudflare.com&gt;

* Apply suggestions from code review

Co-authored-by: Somhairle MacLeòid &lt;smacleod@cloudflare.com&gt;

* Apply suggestions from code review

Co-authored-by: Somhairle MacLeòid &lt;smacleod@cloudflare.com&gt;

* Apply suggestions from code review

Co-authored-by: Somhairle MacLeòid &lt;smacleod@cloudflare.com&gt;

* Apply suggestions from code review

Co-authored-by: Somhairle MacLeòid &lt;smacleod@cloudflare.com&gt;

* Apply suggestions from code review

Co-authored-by: Somhairle MacLeòid &lt;smacleod@cloudflare.com&gt;

* remove preview_id

* Update src/content/docs/d1/best-practices/local-development.mdx

---------

Co-authored-by: Somhairle MacLeòid &lt;smacleod@cloudflare.com&gt;
Co-authored-by: Caley Burton &lt;caley@cloudflare.com&gt;
diff --git a/src/content/docs/browser-rendering/faq.mdx b/src/content/docs/browser-rendering/faq.mdx
@@ -25,7 +25,7 @@ If you cannot find the answer you are looking for, join us on [Discord](https://
 Not yet. Local development currently has the following limitation(s):
 - Requests larger than 1 MB are not supported.
 
-For full feature access, use `npx wrangler dev --remote`.
+For full feature access, set the browser rendering as a [remote binding](/workers/development-testing/#remote-bindings).
 
 ### Will Browser Rendering bypass Cloudflare's Bot Protection?
 
diff --git a/src/content/docs/browser-rendering/how-to/ai.mdx b/src/content/docs/browser-rendering/how-to/ai.mdx
@@ -259,10 +259,10 @@ async function getLLMResult(env, prompt: string, schema?: any) {
 }
 ```
 
-You can run this script to test it using Wrangler's `--remote` flag:
+You can run this script to test it using [remote bindings](/workers/development-testing/#remote-bindings):
 
 ```sh
-npx wrangler dev --remote
+npx wrangler dev
 ```
 
 With your script now running, you can go to `http://localhost:8787/` and should see something like the following:
diff --git a/src/content/docs/browser-rendering/how-to/pdf-generation.mdx b/src/content/docs/browser-rendering/how-to/pdf-generation.mdx
@@ -257,9 +257,9 @@ export default {
 };
 ```
 
-You can run this script to test it using Wrangler’s `--remote` flag:
+You can run this script to test it using [remote bindings](/workers/development-testing/#remote-bindings):
 
-<PackageManagers type="exec" pkg="wrangler" args="dev --remote" />
+<PackageManagers type="exec" pkg="wrangler" args="dev" />
 
 With your script now running, you can pass in a `?name` parameter to the local URL (such as `http://localhost:8787/?name=Harley`) and should see the following:
 
diff --git a/src/content/docs/browser-rendering/platform/wrangler.mdx b/src/content/docs/browser-rendering/platform/wrangler.mdx
@@ -44,4 +44,4 @@ After the binding is declared, access the DevTools endpoint using `env.MYBROWSER
 const browser = await puppeteer.launch(env.MYBROWSER);
 ```
 
-Run `npx wrangler dev` to test your Worker locally or run [`npx wrangler dev --remote`](/workers/wrangler/commands/#dev) to test your Worker remotely before deploying to Cloudflare's global network.
+Run `npx wrangler dev` to test your Worker locally. You can also set the browser binding as a [remote binding](/workers/development-testing/#remote-bindings) to test against a remote browser.
diff --git a/src/content/docs/browser-rendering/workers-bindings/browser-rendering-with-DO.mdx b/src/content/docs/browser-rendering/workers-bindings/browser-rendering-with-DO.mdx
@@ -210,7 +210,7 @@ export class Browser {
 
 ## 6. Test
 
-Run `npx wrangler dev` to test your Worker locally or run [`npx wrangler dev --remote`](/workers/wrangler/commands/#dev) to test your Worker remotely before deploying to Cloudflare's global network.
+Run `npx wrangler dev` to test your Worker locally. You can also set the browser binding as a [remote binding](/workers/development-testing/#remote-bindings) to test against a remote browser.
 
 ## 7. Deploy
 
diff --git a/src/content/docs/browser-rendering/workers-bindings/reuse-sessions.mdx b/src/content/docs/browser-rendering/workers-bindings/reuse-sessions.mdx
@@ -144,7 +144,7 @@ Besides `puppeteer.sessions()`, we have added other methods to facilitate [Sessi
 
 ## 5. Test
 
-Run `npx wrangler dev` to test your Worker locally or run [`npx wrangler dev --remote`](/workers/wrangler/commands/#dev) to test your Worker remotely before deploying to Cloudflare's global network.
+Run `npx wrangler dev` to test your Worker locally. You can also set the browser binding as a [remote binding](/workers/development-testing/#remote-bindings) to test against a remote browser.
 
 To test go to the following URL:
 
diff --git a/src/content/docs/browser-rendering/workers-bindings/screenshots.mdx b/src/content/docs/browser-rendering/workers-bindings/screenshots.mdx
@@ -171,7 +171,7 @@ If the same `"url"` is requested again, it will use the cached version in KV ins
 
 ## 6. Test
 
-Run `npx wrangler dev` to test your Worker locally or run [`npx wrangler dev --remote`](/workers/wrangler/commands/#dev) to test your Worker remotely before deploying to Cloudflare's global network.
+Run `npx wrangler dev` to test your Worker locally. You can also use [remote bindings](/workers/development-testing/#remote-bindings) to test against a remote browser.
 
 To test taking your first screenshot, go to the following URL:
 
diff --git a/src/content/docs/d1/best-practices/local-development.mdx b/src/content/docs/d1/best-practices/local-development.mdx
@@ -67,7 +67,7 @@ database_id = "c020574a-5623-407b-be0c-cd192bab9545"
 
 </WranglerConfig>
 
-Note that `wrangler dev` separates local and production (remote) data. A local session does not have access to your production data by default. To access your production (remote) database, pass the `--remote` flag when calling `wrangler dev`. Any changes you make when running in `--remote` mode cannot be undone.
+Note that `wrangler dev` separates local and production (remote) data. A local session does not have access to your production data by default. To access your production (remote) database, set your D1 as a [remote binding](/workers/development-testing/#remote-bindings). Any changes you make when running against a remote database cannot be undone.
 
 Refer to the [`wrangler dev` documentation](/workers/wrangler/commands/#dev) to learn more about how to configure a local development session.
 
diff --git a/src/content/docs/d1/tutorials/build-an-api-to-access-d1/index.mdx b/src/content/docs/d1/tutorials/build-an-api-to-access-d1/index.mdx
@@ -279,7 +279,9 @@ To create a table in your newly created database:
 Upon successful execution, a new table will be added to your database.
 
 :::note
-The table will be created in the local instance of the database. If you want to add this table to your production database, append the above command by adding the `--remote` flag.
+
+The table will be created in the local instance of the database. If you want to add this table to your production database, set your database as a [remote binding](/workers/development-testing/#remote-bindings).
+
 :::
 
 ## 9. Query the database
diff --git a/src/content/docs/d1/tutorials/using-read-replication-for-e-com/index.mdx b/src/content/docs/d1/tutorials/using-read-replication-for-e-com/index.mdx
@@ -856,7 +856,9 @@ curl -X POST http://localhost:8787/api/product \
 ```
 
 :::note
-Read replication is only used when the application has been [deployed](/d1/tutorials/using-read-replication-for-e-com/#step-9-deploy-the-application). D1 does not create read replicas when you develop locally. To test it locally, you can start the development server with the `--remote` flag.
+
+Read replication is only used when the application has been [deployed](/d1/tutorials/using-read-replication-for-e-com/#step-9-deploy-the-application). D1 does not create read replicas when you develop locally. To test it locally, you can set your database as a [remote binding](/workers/development-testing/#remote-bindings).
+
 :::
 
 ## Step 9: Deploy the application
diff --git a/src/content/docs/kv/concepts/kv-bindings.mdx b/src/content/docs/kv/concepts/kv-bindings.mdx
@@ -58,9 +58,7 @@ export default {
 
 When you use Wrangler to develop locally with the `wrangler dev` command, Wrangler will default to using a local version of KV to avoid interfering with any of your live production data in KV. This means that reading keys that you have not written locally will return `null`.
 
-To have `wrangler dev` connect to your Workers KV namespace running on Cloudflare's global network, call `wrangler dev --remote` instead. This will use the `preview_id` of the KV binding configuration in the Wrangler file. This is how a Wrangler file looks with the `preview_id` specified.
-
-
+To have `wrangler dev` connect to your Workers KV namespace running on Cloudflare's global network, set your KV as a [remote binding](/workers/development-testing/#remote-bindings).
 
 <WranglerConfig>
 
@@ -70,7 +68,7 @@ name = "worker"
 # ...
 
 kv_namespaces = [
-  { binding = "TODO", id = "06779da6940b431db6e566b4846d64db", preview_id="06779da6940b431db6e566b484a6a769a7a" }
+  { binding = "TODO", id = "06779da6940b431db6e566b4846d64db" }
 ]
 ```
 
diff --git a/src/content/docs/kv/get-started.mdx b/src/content/docs/kv/get-started.mdx
@@ -336,7 +336,7 @@ You can view key-value pairs directly from the dashboard.
 
 When using [`wrangler dev`](/workers/wrangler/commands/#dev) to develop locally, Wrangler defaults to using a local version of KV to avoid interfering with any of your live production data in KV. This means that reading keys that you have not written locally returns null.
 
-To have `wrangler dev` connect to your Workers KV namespace running on Cloudflare's global network, call `wrangler dev --remote` instead. This uses the `preview_id` of the KV binding configuration in the Wrangler file. Refer to the [KV binding docs](/kv/concepts/kv-bindings/#use-kv-bindings-when-developing-locally) for more information.
+To have `wrangler dev` connect to your Workers KV namespace running on Cloudflare's global network, you can set the KV as a [remote binding](/workers/development-testing/#remote-bindings) instead. This uses the `preview_id` of the KV binding configuration in the Wrangler file. Refer to the [KV binding docs](/kv/concepts/kv-bindings/#use-kv-bindings-when-developing-locally) for more information.
 
 :::
 
diff --git a/src/content/docs/r2/api/workers/workers-api-usage.mdx b/src/content/docs/r2/api/workers/workers-api-usage.mdx
@@ -83,7 +83,7 @@ Within your Worker code, your bucket is now available under the `MY_BUCKET` vari
 :::caution[Local Development mode in Wrangler]
 
 By default `wrangler dev` runs in local development mode. In this mode, all operations performed by your local worker will operate against local storage on your machine.
-Use `wrangler dev --remote` if you want R2 operations made during development to be performed against a real R2 bucket.
+You can set an R2 as a [remote binding](/workers/development-testing/#remote-bindings) if you want R2 operations made during development to be performed against a real R2 bucket.
 
 :::
 
diff --git a/src/content/docs/workers-ai/guides/tutorials/build-a-retrieval-augmented-generation-ai.mdx b/src/content/docs/workers-ai/guides/tutorials/build-a-retrieval-augmented-generation-ai.mdx
@@ -77,9 +77,15 @@ The Workers command-line interface, [Wrangler](/workers/wrangler/install-and-upd
 After you have created your first Worker, run the [`wrangler dev`](/workers/wrangler/commands/#dev) command in the project directory to start a local server for developing your Worker. This will allow you to test your Worker locally during development.
 
 ```sh
-npx wrangler dev --remote
+npx wrangler dev
 ```
 
+You will now be able to go to [http://localhost:8787](http://localhost:8787) to see your Worker running. Any changes you make to your code will trigger a rebuild, and reloading the page will show you the up-to-date output of your Worker.
+
+## 3. Adding the AI binding
+
+To begin using Cloudflare's AI products, you can add the `ai` block to the [Wrangler configuration file](/workers/wrangler/configuration/) as a [remote binding](/workers/development-testing/#remote-bindings). This will set up a binding to Cloudflare's AI models in your code that you can use to interact with the available AI models on the platform.
+
 :::note
 
 If you have not used Wrangler before, it will try to open your web browser to login with your Cloudflare account.
@@ -88,19 +94,14 @@ If you have issues with this step or you do not have access to a browser interfa
 
 :::
 
-You will now be able to go to [http://localhost:8787](http://localhost:8787) to see your Worker running. Any changes you make to your code will trigger a rebuild, and reloading the page will show you the up-to-date output of your Worker.
-
-## 3. Adding the AI binding
-
-To begin using Cloudflare's AI products, you can add the `ai` block to the [Wrangler configuration file](/workers/wrangler/configuration/). This will set up a binding to Cloudflare's AI models in your code that you can use to interact with the available AI models on the platform.
-
 This example features the [`@cf/meta/llama-3-8b-instruct` model](/workers-ai/models/llama-3-8b-instruct/), which generates text.
 
 <WranglerConfig>
 
 ```toml
 [ai]
 binding = "AI"
+remote = true
 ```
 
 </WranglerConfig>
diff --git a/src/content/docs/workers/development-testing/wrangler-vs-vite.mdx b/src/content/docs/workers/development-testing/wrangler-vs-vite.mdx
@@ -17,7 +17,7 @@ Deciding between Wrangler and the Cloudflare Vite plugin depends on your project
   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.
+  If your project needs the ability to run your worker remotely 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.
diff --git 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/development-testing/#remote-bindings).
+to specific routes, or using production-like data via [remote bindings](/workers/development-testing/#remote-bindings).
 
 ## Taking a profile
 
diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx
@@ -646,7 +646,7 @@ To bind KV namespaces to your Worker, assign an array of the below object to the
   - The ID of the KV namespace.
 
 - `preview_id` <Type text="string" /> <MetaInfo text="optional" />
-  - The preview ID of this KV namespace. This option is **required** when using `wrangler dev --remote` to develop against remote resources. If developing locally (without `--remote`), this is an optional field. `wrangler dev` will use this ID for the KV namespace. Otherwise, `wrangler dev` will use `id`.
+  - The preview ID of this KV namespace. This option is **required** when using `wrangler dev --remote` to develop against remote resources (but is not required with [remote bindings](/workers/development-testing/#remote-bindings)). If developing locally, this is an optional field. `wrangler dev` will use this ID for the KV namespace. Otherwise, `wrangler dev` will use `id`.
 
 :::note
 
@@ -757,7 +757,7 @@ To bind R2 buckets to your Worker, assign an array of the below object to the `r
   - The jurisdiction where this R2 bucket is located, if a jurisdiction has been specified. Refer to [Jurisdictional Restrictions](/r2/reference/data-location/#jurisdictional-restrictions).
 
 - `preview_bucket_name` <Type text="string" /> <MetaInfo text="optional" />
-  - The preview name of this R2 bucket. If provided, `wrangler dev` will use this name for the R2 bucket. Otherwise, it will use `bucket_name`. This option is required when using `wrangler dev --remote`.
+  - The preview name of this R2 bucket. If provided, `wrangler dev` will use this name for the R2 bucket. Otherwise, it will use `bucket_name`. This option is required when using `wrangler dev --remote` (but is not required with [remote bindings](/workers/development-testing/#remote-bindings)).
 
 :::note
 
diff --git a/src/content/docs/workflows/build/local-development.mdx b/src/content/docs/workflows/build/local-development.mdx
@@ -54,6 +54,6 @@ Refer to the [`wrangler dev` documentation](/workers/wrangler/commands/#dev) to
 
 ## Known Issues
 
-Workflows does not support `npx wrangler dev --remote`.
+Workflows are not supported as [remote bindings](/workers/development-testing/#remote-bindings) or when using `npx wrangler dev --remote`.
 
 Wrangler Workflows commands `npx wrangler workflow [cmd]` are not supported for local development, as they target production API.
diff --git a/src/content/partials/workers/wrangler-commands/d1.mdx b/src/content/partials/workers/wrangler-commands/d1.mdx
@@ -80,7 +80,7 @@ You must provide either `--command` or `--file` for this command to run successf
 - `--local` <Type text="boolean" /> <MetaInfo text="(default: true) optional" />
   - Execute commands/files against a local database for use with [wrangler dev](/workers/wrangler/commands/#dev).
 - `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
-  - Execute commands/files against a remote D1 database for use with [wrangler dev --remote](/workers/wrangler/commands/#dev).
+  - Execute commands/files against a remote D1 database for use with [remote binding](/workers/development-testing/#remote-bindings) or your deployed Worker.
 - `--persist-to` <Type text="string" /> <MetaInfo text="optional" />
   - Specify directory to use for local persistence (for use in combination with `--local`).
 - `--json` <Type text="boolean" /> <MetaInfo text="optional" />
@@ -101,7 +101,7 @@ wrangler d1 export <DATABASE_NAME> [OPTIONS]
 - `--local` <Type text="boolean" /> <MetaInfo text="(default: true) optional" />
   - Export from a local database for use with [wrangler dev](/workers/wrangler/commands/#dev).
 - `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
-  - Export from a remote D1 database for use with [wrangler dev --remote](/workers/wrangler/commands/#dev).
+  - Export from a remote D1 database.
 - `--output` <Type text="string" /> <MetaInfo text="required" />
   - Path to the SQL file for your export.
 - `--table` <Type text="string" /> <MetaInfo text="optional" />
