New Vite plugin docs for local development

src/content/docs/workers/local-development.mdx

@@ -2,7 +2,7 @@
 title: Local development
 pcx_content_type: concept
 sidebar:
-  order: 5
+  order: 14
 head: []
 description: Develop your Workers locally via Wrangler.
 ---

src/content/docs/workers/local-development/bindings-per-env.mdx

@@ -0,0 +1,12 @@
+---
+pcx_content_type: navigation
+title: Supported bindings in local and remote dev
+sidebar:
+  order: 4
+head: []
+description: Supported bindings in local and remote development
+---
+
+import { Render } from "~/components";
+
+<Render file="bindings_per_env" />

src/content/docs/workers/local-development/environment-variables.mdx

@@ -0,0 +1,80 @@
+---
+pcx_content_type: navigation
+title: Environment variables and secrets
+sidebar:
+  order: 1
+head: []
+description: Configuring environment variables and secrets for local development
+---
+
+import { Aside, PackageManagers, Steps } from "~/components";
+
+During local development, you may need to configure **environment variables** (such as API URLs, feature flags) and **secrets** (API tokens, private keys). You can use a `.dev.vars` file in the root of your project to override environment variables for local development, and both [Wrangler](/workers/configuration/environment-variables/#compare-secrets-and-environment-variables) and the [Vite plugin](/workers/vite-plugin/reference/secrets/) will respect this override.
+
+<Aside type="caution">
+	Be sure to add `.dev.vars` to your `.gitignore` so it never gets committed.
+</Aside>
+
+### Why use a `.dev.vars` file?
+
+While [`.dev.vars` is commonly used for storing secrets](/workers/configuration/environment-variables/#compare-secrets-and-environment-variables), the file is really just a local override for **any** environment variable — secret or otherwise. This allows you to avoid polluting environment variables in your Wrangler configuration, and provide a way to set local-only values.
+
+You can also define [environment variables as `[vars]`](/workers/wrangler/environments/#_top) in your Wrangler configuration (for `development`, `staging`, `production`, etc). This is a good way to manage environment-based configuration that you **want checked into your repository** (for example, non-sensitive or shared environment defaults). Using a `.dev.vars` file is specifically for local-only secrets or configuration that you do not want in version control and only want to inject in local dev sessions.
+
+## Basic setup
+
+<Steps>
+
+1.  Create a `.dev.vars` file in your project root.
+
+2.  Add key-value pairs:
+
+    ```ini title=".dev.vars"
+    API_HOST="localhost:3000"
+    DEBUG="true"
+    SECRET_TOKEN="my-local-secret-token"
+    ```
+
+3.  Run your `dev` command
+
+        **Wrangler**
+        <PackageManagers type="exec" pkg="wrangler" args="dev" />
+
+
+        **Vite plugin**
+        <PackageManagers type="run" args="dev" />
+
+</Steps>
+
+## Multiple local environments with `.dev.vars`
+
+To simulate different local environments, you can:
+
+<Steps>
+
+1.  Create a file named `.dev.vars.<environment-name>` . For example, we'll use `.dev.vars.staging`.
+
+2.  Add key-value pairs:
+    ```ini title=".dev.vars.staging"
+    API_HOST="staging.localhost:3000"
+    DEBUG="false"
+    SECRET_TOKEN="staging-token"
+    ```
+3.  Run your `dev` command with an `--env` flag:
+
+        **Wrangler**
+
+        <PackageManagers type="exec" pkg="wrangler" args="dev --env staging" />
+
+        **Vite plugin**
+
+        <PackageManagers type="run" args="dev --env staging" />
+
+        Only the values from `.dev.vars.staging` will be applied instead of `.dev.vars`.
+
+</Steps>
+
+## Learn more
+
+- To learn how to configure multiple environments in Wrangler configuration, [read the documenation](/workers/wrangler/environments/#_top).
+- To learn how to use Wrangler environments and Vite environments together, [read the Vite plugin documentation](/workers/vite-plugin/reference/cloudflare-environments/)

src/content/docs/workers/local-development/index.mdx

@@ -0,0 +1,78 @@
+---
+pcx_content_type: navigation
+title: Local development
+sidebar:
+  order: 6
+head: []
+description: Develop your Workers locally.
+---
+
+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 that provides remote development with the `wrangler dev --remote` command.
+
+<LinkCard
+	title="Choosing between Wrangler and Vite"
+	href="/workers/local-development/wrangler-vs-vite/"
+/>
+
+## Install and start your development server
+
+### Wrangler
+
+#### Installation
+
+To install [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler), ensure you have [Node.js](https://nodejs.org/en/) and [npm](https://docs.npmjs.com/getting-started) installed, preferably using a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm).
+
+<Render file="install_wrangler" />
+
+#### Start a development server
+
+To start a development server using Wrangler, run the following:
+
+<PackageManagers type="exec" pkg="wrangler" args="dev" />
+
+<LinkCard title="Learn more about Wrangler" href="/workers/wrangler/" />
+
+### Vite Plugin
+
+#### Installation
+
+To install the Cloudflare Vite plugin, first start with a simple `package.json`
+
+```json title="package.json"
+{
+	"name": "cloudflare-vite-get-started",
+	"private": true,
+	"version": "0.0.0",
+	"type": "module",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build",
+		"preview": "npm run build && vite preview",
+		"deploy": "npm run build && wrangler deploy"
+	}
+}
+```
+
+Then, install the necessary development depenencies:
+
+<PackageManagers type="add" pkg="vite @cloudflare/vite-plugin wrangler" dev />
+
+This command will install `vite`, along with `@cloudflare/vite-plugin` and `wrangler` as `devDependencies` in your `package.json`.
+
+#### Start a development server
+
+You can then start a development server by running:
+
+<PackageManagers type="run" args="dev" />
+
+<LinkCard
+	title="Learn more about the Vite plugin"
+	href="/workers/vite-plugin/"
+/>

src/content/docs/workers/local-development/local-data.mdx

@@ -0,0 +1,166 @@
+---
+pcx_content_type: navigation
+title: Local data
+sidebar:
+  order: 2
+head: []
+description: Working with data during local development
+---
+
+import {
+	Details,
+	LinkCard,
+	Render,
+	PackageManagers,
+	FileTree,
+	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.
+
+### How it works
+
+When you run either `wrangler dev` or [`vite`](https://vite.dev/guide/cli#dev-server), [Miniflare](/workers/testing/miniflare/) automatically creates **local versions** of your resources (like [KV](/kv), [D1](/d1/), or [R2](/r2)). This means you **don’t** need to manually set up separate local instances for each service. However, newly created local resources **won’t** contain any data — you'll need to use Wrangler commands with the `--local` flag to populate them. Changes made to local resources won’t affect production data.
+
+## Populating local resources with data
+
+When you first start developing, your local resources will be empty. You'll need to populate them with data for testing, using the Wrangler CLI. The Vite plugin doesn't provide any special functionality for populating data - it relies entirely on Wrangler CLI commands with the `--local` flag.
+
+### KV namespaces
+
+<Aside type="caution" title="Syntax note">
+
+Since version 3.60.0, Wrangler supports the `kv ...` syntax. If you are using versions below 3.60.0, the command follows the `kv:...` syntax. Learn more about the deprecation of the `kv:...` syntax in the[Wrangler commands for KV page](/kv/reference/kv-commands/).
+
+</Aside>
+
+#### [Add a single key-value pair](/workers/wrangler/commands/#kv-key)
+
+<PackageManagers
+	type="exec"
+	pkg="wrangler"
+	args="kv key put <KEY> <VALUE> --binding=<BINDING> --local "
+/>
+
+#### [Buld upload](/workers/wrangler/commands/#kv-bulk)
+
+<PackageManagers
+	type="exec"
+	pkg="wrangler"
+	args="kv bulk put <FILENAME.json> --binding=<BINDING> --local"
+/>
+
+### R2 buckets
+
+#### [Upload a file](/workers/wrangler/commands/#r2-object)
+
+<PackageManagers
+	type="exec"
+	pkg="wrangler"
+	args="r2 object put <BUCKET>/<KEY> --file=<PATH_TO_FILE> --local"
+/>
+
+You may also include [other metadata](/workers/wrangler/commands/#r2-object-put).
+
+### D1 databases
+
+#### [Execute a SQL statement](/wrangler/commands/#d1-execute)
+
+<PackageManagers
+	type="exec"
+	pkg="wrangler"
+	args='d1 execute <DATABASE_NAME> --command="<SQL_QUERY>" --local'
+/>
+
+#### [Execute a SQL file](/wrangler/commands/#d1-execute)
+
+<PackageManagers
+	type="exec"
+	pkg="wrangler"
+	args="wrangler d1 execute <DATABASE_NAME> --file=./schema.sql --local"
+/>
+
+### Durable Objects
+
+For Durable Objects, unlike KV, D1, and R2, there are no CLI commands to populate them with test data. To add data to Durable Objects during local development, you must write application code that creates Durable Object instances and [calls methods on them that store state](/durable-objects/best-practices/access-durable-objects-storage/). This typically involves creating development endpoints or test routes that initialize your Durable Objects with the desired data.
+
+## Where local data gets stored
+
+By default, both Wrangler and the Vite plugin store local binding data in the same location: the `.wrangler/state` folder in your project directory. This folder stores data in subdirectories for all local bindings: KV namespaces, R2 buckets, D1 databases, Durable Objects, etc.
+
+### Clearing local storage
+
+You can delete the `.wrangler/state` folder at any time to reset your local environment, and Miniflare will recreate it the next time you run your `dev` command. You can also delete specific sub-folders within `.wrangler/state` for more targeted clean-up.
+
+### Changing the local data directory
+
+If you prefer to specify a different directory for local storage, you can do so through the Wranlger CLI or in the Vite plugin's configuration.
+
+#### Using Wrangler
+
+Use the [`--persist-to`](/workers/wrangler/commands/#dev) flag with `wrangler dev`. You need to specify this flag every time you run the `dev` command:
+
+<PackageManagers
+	type="exec"
+	pkg="wrangler"
+	args="dev --persist-to <DIRECTORY>"
+/>
+
+:::note
+The local persistence folder (like `.wrangler/state` or any custom folder you set) should be added to your `.gitignore` to avoid committing local development data to version control.
+:::
+
+<Details header="Using `--local` with `--persist-to`">
+If you run `wrangler dev --persist-to <DIRECTORY>` to specify a custom location for local data, you must also include the same `--persist-to <DIRECTORY>` when running other Wrangler commands that modify local data (and be sure to include the `--local` flag).
+
+For example, to create a KV key named `test` with a value of `12345` in a local KV namespace, run:
+
+<PackageManagers
+	type="exec"
+	pkg="wrangler"
+	args="kv key put test 12345 --binding MY_KV_NAMESPACE --local --persist-to worker-local"
+/>
+
+This command:
+
+- Sets the KV key `test` to `12345` in the binding `MY_KV_NAMESPACE` (defined in your [Wrangler configuration file](/workers/wrangler/configuration/)).
+- Uses `--persist-to worker-local` to ensure the data is created in the **worker-local** directory instead of the default `.wrangler/state`.
+- Adds the `--local` flag, indicating you want to modify local data.
+
+If `--persist-to` is not specified, Wrangler defaults to using `.wrangler/state` for local data.
+
+</Details>
+
+#### Using the Cloudflare Vite plugin
+
+To customize where the Vite plugin stores local data, configure the [`persistState` option](/workers/vite-plugin/reference/api/#interface-pluginconfig) in your Vite config file:
+
+```js title="vite.config.js"
+import { defineConfig } from "vite";
+import { cloudflare } from "@cloudflare/vite-plugin";
+
+export default defineConfig({
+	plugins: [
+		cloudflare({
+			persistState: "./my-custom-directory",
+		}),
+	],
+});
+```
+
+#### Sharing state between tools
+
+If you want Wrangler and the Vite plugin to share the same state, configure them to use the same persistence path.
+
+## Customize `wrangler dev`
+
+You can further customize the behavior of `wrangler dev` (for instance, by changing ports or skipping Wrangler's build steps). Refer to [the `wrangler dev` documentation](/workers/wrangler/commands/#dev) for available configuration options.
+
+## Customize the Cloudflare Vite plugin
+
+You can also [customize the Vite plugin](/workers/vite-plugin/reference/api/), such as changing ports or calling other Workers.
+
+## Debugging
+
+- [DevTools](/workers/observability/dev-tools) - Guides to using DevTools to debug your Worker locally.
+- [Debugging with the Vite plugin](/workers/vite-plugin/reference/debugging/)