diff --git a/src/assets/images/changelog/workers/fullstack-on-workers.png b/src/assets/images/changelog/workers/fullstack-on-workers.png new file mode 100644 index 000000000000000..e8500bdcf0572eb Binary files /dev/null and b/src/assets/images/changelog/workers/fullstack-on-workers.png differ diff --git a/src/content/changelog/workers/2025-04-07-fullstack-on-workers.mdx b/src/content/changelog/workers/2025-04-07-fullstack-on-workers.mdx new file mode 100644 index 000000000000000..3418c2b8424a7a3 --- /dev/null +++ b/src/content/changelog/workers/2025-04-07-fullstack-on-workers.mdx @@ -0,0 +1,38 @@ +--- +title: Full-stack frameworks now generally available on Cloudflare Workers +description: Cloudflare Workers now provides production ready, generally available (GA) support for React Router v7 (Remix), Astro, Hono, Vue.js, Nuxt, Svelte (SvelteKit), and more. +products: + - workers + - workers-for-platforms +date: 2025-04-08T18:00:00Z +hidden: true +--- + +import { Image } from "astro:assets"; +import fullstackWorkers from "~/assets/images/changelog/workers/fullstack-on-workers.png"; + +Fullstack on Cloudflare Workers + +We're excited to announce that the following frameworks are now fully supported and **generally available** on Cloudlfare Workers: + +- [React Router v7 (Remix)](/workers/frameworks/framework-guides/remix/) +- [Astro](/workers/frameworks/framework-guides/astro/) +- [Hono](/workers/frameworks/framework-guides/hono/) +- [Vue.js](/workers/frameworks/framework-guides/vue/) +- [Nuxt](/workers/frameworks/framework-guides/nuxt/) +- [Svelte (SvelteKit)](/workers/frameworks/framework-guides/svelte/) +- And [more](/workers/frameworks/). + +The following frameworks are still in **beta**, but will be fully supported and GA in the next few months: + +- [Next.js](/workers/frameworks/framework-guides/nextjs/), supported through [@opennextjs/cloudflare](/https://opennext.js.org/cloudflare) is now `v1.0-beta`. Those using the OpenNext adapter will also be able to easily upgrade to the [recently announced Next.js Deployments API](https://github.com/vercel/next.js/discussions/77740). +- [Angular](/workers/frameworks/framework-guides/angular/) +- [SolidJS (SolidStart)](/workers/frameworks/framework-guides/solid/) + +You can also build complete full-stack apps on Workers **without a framework**: + +- You can [“just use Vite"](https://blog.cloudflare.com/introducing-the-cloudflare-vite-plugin) and React together, and build a backend API in the same Worker. Follow our [React SPA with an API tutorial](/workers/vite-plugin/tutorial/) to learn how. + +All together, these new additions allow you to build and host projects ranging from simple static sites to full-stack applications, all on Cloudflare Workers. + +**Get started building today with our [Framework guides](/workers/frameworks/)**. Or, read more about our updates to building full-stack applications on Workers in our [Dev Week 2025 blog](https://blog.cloudflare.com/full-stack-development-on-cloudflare-workers). diff --git a/src/content/docs/workers/local-development.mdx b/src/content/docs/workers/local-development.mdx index 1d1c5a567280021..184413426fcfa52 100644 --- a/src/content/docs/workers/local-development.mdx +++ b/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. --- diff --git a/src/content/docs/workers/local-development/bindings-per-env.mdx b/src/content/docs/workers/local-development/bindings-per-env.mdx new file mode 100644 index 000000000000000..62a4c347df5add7 --- /dev/null +++ b/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"; + + diff --git a/src/content/docs/workers/local-development/environment-variables.mdx b/src/content/docs/workers/local-development/environment-variables.mdx new file mode 100644 index 000000000000000..eca45c3ce77635a --- /dev/null +++ b/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. + + + +### Why use a `.dev.vars` file? + +Use `.dev.vars` to set local overrides for environment variables that should not be checked into your repository. + +If you want to manage environment-based configuration that you **want checked into your repository** (for example, non-sensitive or shared environment defaults), you can define [environment variables as `[vars]`](/workers/wrangler/environments/#_top) in your Wrangler configuration. 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 + + + +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** + + + + **Vite plugin** + + + + +## Multiple local environments with `.dev.vars` + +To simulate different local environments, you can: + + + +1. Create a file named `.dev.vars.` . 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. Specify the environment when running the `dev` command: + + **Wrangler** + + + + **Vite plugin** + + + + Only the values from `.dev.vars.staging` will be applied instead of `.dev.vars`. + + + +## 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/) diff --git a/src/content/docs/workers/local-development/index.mdx b/src/content/docs/workers/local-development/index.mdx new file mode 100644 index 000000000000000..c354b6110cb1141 --- /dev/null +++ b/src/content/docs/workers/local-development/index.mdx @@ -0,0 +1,51 @@ +--- +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, and provides remote development via the `wrangler dev --remote` command. + +## Choosing between Wrangler or 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. diff --git a/src/content/docs/workers/local-development/local-data.mdx b/src/content/docs/workers/local-development/local-data.mdx new file mode 100644 index 000000000000000..471ee7eeb76d86f --- /dev/null +++ b/src/content/docs/workers/local-development/local-data.mdx @@ -0,0 +1,153 @@ +--- +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 using the Wrangler CLI. + +### KV namespaces + + + +#### [Add a single key-value pair](/workers/wrangler/commands/#kv-key) + + + +#### [Buld upload](/workers/wrangler/commands/#kv-bulk) + + + +### R2 buckets + +#### [Upload a file](/workers/wrangler/commands/#r2-object) + + + +You may also include [other metadata](/workers/wrangler/commands/#r2-object-put). + +### D1 databases + +#### [Execute a SQL statement](/workers/wrangler/commands/#d1-execute) + + + +#### [Execute a SQL file](/workers/wrangler/commands/#d1-execute) + + + +### Durable Objects + +For Durable Objects, unlike KV, D1, and R2, there are no CLI commands to populate them with local 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: + + + +:::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. +::: + +
+If you run `wrangler dev --persist-to ` to specify a custom location for local data, you must also include the same `--persist-to ` 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: + + + +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. + +
+ +#### 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. diff --git a/src/content/docs/workers/local-development/remote-data.mdx b/src/content/docs/workers/local-development/remote-data.mdx new file mode 100644 index 000000000000000..9dca3ae6b8ba8ff --- /dev/null +++ b/src/content/docs/workers/local-development/remote-data.mdx @@ -0,0 +1,53 @@ +--- +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/wrangler-vs-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/partials/workers/bindings_per_env.mdx b/src/content/partials/workers/bindings_per_env.mdx new file mode 100644 index 000000000000000..ab81c5de358c569 --- /dev/null +++ b/src/content/partials/workers/bindings_per_env.mdx @@ -0,0 +1,45 @@ +--- +{} +--- + +**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. + +---