From 35b75f0ee8da4431b527ffc0cece2db5f707439d Mon Sep 17 00:00:00 2001 From: Thomas Gauvin <35609369+thomasgauvin@users.noreply.github.com> Date: Sat, 6 Jun 2026 18:08:18 -0400 Subject: [PATCH 1/3] [Workers] Add existing project deployment guide for React + Vite --- .../framework-guides/web-apps/react.mdx | 184 ++++++++++++---- .../docs/workers/vite-plugin/tutorial.mdx | 200 ++---------------- .../workers/vite-plugin/add-api-worker.mdx | 56 +++++ .../workers/vite-plugin/add-dependencies.mdx | 9 + .../vite-plugin/add-plugin-to-vite-config.mdx | 19 ++ .../vite-plugin/add-tsconfig-worker.mdx | 35 +++ .../workers/vite-plugin/add-worker-config.mdx | 27 +++ .../workers/vite-plugin/build-app.mdx | 16 ++ .../vite-plugin/create-wrangler-config.mdx | 41 ++++ .../partials/workers/vite-plugin/deploy.mdx | 13 ++ .../workers/vite-plugin/preview-app.mdx | 13 ++ .../workers/vite-plugin/run-dev-server.mdx | 14 ++ .../workers/vite-plugin/update-gitignore.mdx | 13 ++ 13 files changed, 411 insertions(+), 229 deletions(-) create mode 100644 src/content/partials/workers/vite-plugin/add-api-worker.mdx create mode 100644 src/content/partials/workers/vite-plugin/add-dependencies.mdx create mode 100644 src/content/partials/workers/vite-plugin/add-plugin-to-vite-config.mdx create mode 100644 src/content/partials/workers/vite-plugin/add-tsconfig-worker.mdx create mode 100644 src/content/partials/workers/vite-plugin/add-worker-config.mdx create mode 100644 src/content/partials/workers/vite-plugin/build-app.mdx create mode 100644 src/content/partials/workers/vite-plugin/create-wrangler-config.mdx create mode 100644 src/content/partials/workers/vite-plugin/deploy.mdx create mode 100644 src/content/partials/workers/vite-plugin/preview-app.mdx create mode 100644 src/content/partials/workers/vite-plugin/run-dev-server.mdx create mode 100644 src/content/partials/workers/vite-plugin/update-gitignore.mdx diff --git a/src/content/docs/workers/framework-guides/web-apps/react.mdx b/src/content/docs/workers/framework-guides/web-apps/react.mdx index 283d183a4b2..e76a723d554 100644 --- a/src/content/docs/workers/framework-guides/web-apps/react.mdx +++ b/src/content/docs/workers/framework-guides/web-apps/react.mdx @@ -18,8 +18,17 @@ import { Details, FileTree, Steps, + Tabs, + TabItem, } from "~/components"; +[React](https://react.dev/) is a framework for building user interfaces. It allows you to create reusable UI components and manage the state of your application efficiently. You can use React to build a single-page application (SPA), and combine it with a backend API running on Cloudflare Workers to create a full-stack application. + +This guide shows you how to deploy a React + Vite application to Cloudflare Workers. You can either create a new project using the `create-cloudflare` CLI (C3) or adapt an existing React + Vite project. + + + + **Start from CLI** - scaffold a full-stack app with a React SPA, Cloudflare Workers API, and the [Cloudflare Vite plugin](/workers/vite-plugin/) for lightning-fast development. + --- **Or just deploy** - create a full-stack app using React, a Workers API, and Vite, with CI/CD and previews all set up for you. [![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create/deploy-to-workers&repository=https://github.com/cloudflare/templates/tree/main/react-starter-template) -## What is React? - -[React](https://react.dev/) is a framework for building user interfaces. It allows you to create reusable UI components and manage the state of your application efficiently. You can use React to build a single-page application (SPA), and combine it with a backend API running on Cloudflare Workers to create a full-stack application. - -## Creating a full-stack app with React - 1. **Create a new project with the create-cloudflare CLI (C3)** - +
- Below is a simplified file tree of the project. - - - my-react-app - - src/ - - App.tsx - - worker/ - - index.ts - - index.html - - vite.config.ts - - wrangler.jsonc - - - `wrangler.jsonc` is your [Wrangler configuration file](/workers/wrangler/configuration/). - In this file: - - `main` points to `worker/index.ts`. This is your Worker, which is going to act as your backend API. - - `assets.not_found_handling` is set to `single-page-application`, which means that routes that are handled by your React SPA do not go to the Worker, and are thus free. - - If you want to add bindings to resources on Cloudflare's developer platform, you configure them here. Read more about [bindings](/workers/runtime-apis/bindings/). - - `vite.config.ts` is set up to use the [Cloudflare Vite plugin](/workers/vite-plugin/). This runs your Worker in the Cloudflare Workers runtime, ensuring your local development environment is as close to production as possible. - - `worker/index.ts` is your backend API, which contains a single endpoint, `/api/`, that returns a text response. - At `src/App.tsx`, your React app calls this endpoint to get a message back and displays this. -
+ Below is a simplified file tree of the project. + + - my-react-app + - src/ + - App.tsx + - worker/ + - index.ts + - index.html + - vite.config.ts + - wrangler.jsonc + + + `wrangler.jsonc` is your [Wrangler configuration file](/workers/wrangler/configuration/). + In this file: + - `main` points to `worker/index.ts`. This is your Worker, which is going to act as your backend API. + - `assets.not_found_handling` is set to `single-page-application`, which means that routes that are handled by your React SPA do not go to the Worker, and are thus free. + - If you want to add bindings to resources on Cloudflare's developer platform, you configure them here. Read more about [bindings](/workers/runtime-apis/bindings/). + + `vite.config.ts` is set up to use the [Cloudflare Vite plugin](/workers/vite-plugin/). This runs your Worker in the Cloudflare Workers runtime, ensuring your local development environment is as close to production as possible. + + `worker/index.ts` is your backend API, which contains a single endpoint, `/api/`, that returns a text response. + At `src/App.tsx`, your React app calls this endpoint to get a message back and displays this. + 2. **Develop locally with the [Cloudflare Vite plugin](/workers/vite-plugin/)** After creating your project, run the following command in your project directory to start a local development server.
- This project uses Vite for local development and build, and thus comes with all of Vite's features, including hot module replacement (HMR). + This project uses Vite for local development and build, and thus comes with all of Vite's features, including hot module replacement (HMR). - In addition, `vite.config.ts` is set up to use the Cloudflare Vite plugin. This runs your application in the Cloudflare Workers runtime, just like in production, and enables access to local emulations of bindings. -
+ In addition, `vite.config.ts` is set up to use the Cloudflare Vite plugin. This runs your application in the Cloudflare Workers runtime, just like in production, and enables access to local emulations of bindings. + 3. **Deploy your project** - Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including Cloudflare's own [Workers Builds](/workers/ci-cd/builds/). + Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including Cloudflare's own [Workers Builds](/workers/ci-cd/builds/). + + The following command will build and deploy your project. If you are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately. + + + + + + + + +If you already have a React + Vite application, you can adapt it to deploy to Cloudflare Workers using the Cloudflare Vite plugin. This approach preserves your existing code while adding the ability to deploy to Cloudflare's edge network with static assets and an optional API Worker. + + +1. **Navigate to your project directory** + + Open your existing React + Vite project in your editor of choice. If you don't have one yet, scaffold a new project with Vite first: + + + + Next, open the `my-react-app` directory in your editor of choice. + +2. **Add the Cloudflare Vite plugin** + + + + + + Refer to the [API reference](/workers/vite-plugin/reference/api/) for configuration options. + +3. **Add a Wrangler configuration file** - The following command will build and deploy your project. If you are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately. + - +4. **Update the `.gitignore` file** + + + +5. **Develop locally** + + + +6. **Build and deploy your project** + + + + + + +### Add an API Worker to an existing project + +If you want to add an API Worker to your existing React + Vite project, follow these additional steps: + + +1. **Configure TypeScript for your Worker code** + + + +2. **Add the Worker entrypoint to your configuration** + + + +3. **Add your API Worker** + + + +4. **Call the API from the client** + + You can now call your API from your React components. For example, in `src/App.tsx`: + + ```tsx title="src/App.tsx" + import { useState } from "react"; + + function App() { + const [name, setName] = useState("unknown"); + + return ( +
+ +
+ ); + } + + export default App; + ``` + + + + + + --- ## Asset Routing @@ -102,6 +204,6 @@ If you're using React as a SPA, you will want to set `not_found_handling = "sing ## Use bindings with React -Your new project also contains a Worker at `./worker/index.ts`, which you can use as a backend API for your React application. While your React application cannot directly access Workers bindings, it can interact with them through this Worker. You can make [`fetch()` requests](/workers/runtime-apis/fetch/) from your React application to the Worker, which can then handle the request and use bindings. Learn how to [configure Workers bindings](/workers/runtime-apis/bindings/). +Your project can also contain a Worker at `./worker/index.ts`, which you can use as a backend API for your React application. While your React application cannot directly access Workers bindings, it can interact with them through this Worker. You can make [`fetch()` requests](/workers/runtime-apis/fetch/) from your React application to the Worker, which can then handle the request and use bindings. Learn how to [configure Workers bindings](/workers/runtime-apis/bindings/). diff --git a/src/content/docs/workers/vite-plugin/tutorial.mdx b/src/content/docs/workers/vite-plugin/tutorial.mdx index 9ae1ae30e6b..dc5d022c699 100644 --- a/src/content/docs/workers/vite-plugin/tutorial.mdx +++ b/src/content/docs/workers/vite-plugin/tutorial.mdx @@ -10,7 +10,7 @@ products: - workers --- -import { PackageManagers, WranglerConfig } from "~/components"; +import { PackageManagers, Render } from "~/components"; This tutorial takes you through the steps needed to adapt a Vite project to use the Cloudflare Vite plugin. Much of the content can also be applied to adapting existing Vite projects and to front-end frameworks other than React. @@ -40,172 +40,23 @@ Start by creating a React TypeScript project with Vite. Next, open the `cloudflare-vite-tutorial` directory in your editor of choice. -### Add the Cloudflare dependencies + - + -### Add the plugin to your Vite config + -```ts {3, 6} title="vite.config.ts" -import { defineConfig } from "vite"; -import react from "@vitejs/plugin-react"; -import { cloudflare } from "@cloudflare/vite-plugin"; + -export default defineConfig({ - plugins: [react(), cloudflare()], -}); -``` - -The Cloudflare Vite plugin doesn't require any configuration by default and will look for a `wrangler.jsonc`, `wrangler.json` or `wrangler.toml` in the root of your application. - -Refer to the [API reference](/workers/vite-plugin/reference/api/) for configuration options. - -### Create your Worker config file - - - -```jsonc -{ - "$schema": "./node_modules/wrangler/config-schema.json", - "name": "cloudflare-vite-tutorial", - "compatibility_date": "$today", - "assets": { - "not_found_handling": "single-page-application" - } -} -``` - - - -The [`not_found_handling`](/workers/static-assets/routing/single-page-application/) value has been set to `single-page-application`. -This means that all not found requests will serve the `index.html` file. -With the Cloudflare plugin, the `assets` routing configuration is used in place of Vite's default behavior. -This ensures that your application's [routing configuration](/workers/static-assets/routing/) works the same way while developing as it does when deployed to production. - -Note that the [`directory`](/workers/static-assets/binding/#directory) field is not used when configuring assets with Vite. -The `directory` in the output configuration will automatically point to the client build output. -See [Static Assets](/workers/vite-plugin/reference/static-assets/) for more information. - -:::note -When using the Cloudflare Vite plugin, the Worker config (for example, `wrangler.jsonc`) that you provide is the input configuration file. -A separate output `wrangler.json` file is created when you run `vite build`. -This output file is a snapshot of your configuration at the time of the build and is modified to reference your build artifacts. -It is the configuration that is used for preview and deployment. -::: - -### Update the .gitignore file - -When developing Workers, additional files are used and/or generated that should not be stored in git. -Add the following lines to your `.gitignore` file: - -```txt title=".gitignore" -.wrangler -.dev.vars* -``` - -### Run the development server - -Run `npm run dev` to start the Vite development server and verify that your application is working as expected. - -For a purely front-end application, you could now build (`npm run build`), preview (`npm run preview`), and deploy (`npm exec wrangler deploy`) your application. -This tutorial, however, will show you how to go a step further and add an API Worker. + ## Add an API Worker -### Configure TypeScript for your Worker code - - - -```jsonc title="tsconfig.worker.json" -{ - "extends": "./tsconfig.node.json", - "compilerOptions": { - "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.worker.tsbuildinfo", - "types": ["@cloudflare/workers-types", "vite/client"], - }, - "include": ["worker"], -} -``` - -```jsonc {6} title="tsconfig.json" -{ - "files": [], - "references": [ - { "path": "./tsconfig.app.json" }, - { "path": "./tsconfig.node.json" }, - { "path": "./tsconfig.worker.json" }, - ], -} -``` - -### Add to your Worker configuration + - + -```jsonc -{ - "$schema": "./node_modules/wrangler/config-schema.json", - "name": "cloudflare-vite-tutorial", - "compatibility_date": "$today", - "assets": { - "not_found_handling": "single-page-application" - }, - "main": "./worker/index.ts" -} -``` - - - -The `main` field specifies the entry file for your Worker code. - -### Add your API Worker - -```ts title="worker/index.ts" -export default { - fetch(request) { - const url = new URL(request.url); - - if (url.pathname.startsWith("/api/")) { - return Response.json({ - name: "Cloudflare", - }); - } - - return new Response(null, { status: 404 }); - }, -} satisfies ExportedHandler; -``` - -The Worker above will be invoked for any non-navigation request that does not match a static asset. -It returns a JSON response if the `pathname` starts with `/api/` and otherwise return a `404` response. - -:::note -For top-level navigation requests, browsers send a `Sec-Fetch-Mode: navigate` header. -If this is present and the URL does not match a static asset, the `not_found_handling` behavior will be invoked rather than the Worker. -This implicit routing is the default behavior. - -If you would instead like to define the routes that invoke your Worker explicitly, you can provide an array of route patterns to [`run_worker_first`](/workers/static-assets/binding/#run_worker_first). -This opts out of interpreting the `Sec-Fetch-Mode` header. - - - -```jsonc -{ - "$schema": "./node_modules/wrangler/config-schema.json", - "name": "cloudflare-vite-tutorial", - "compatibility_date": "$today", - "assets": { - "not_found_handling": "single-page-application", - "run_worker_first": [ - "/api/*" - ] - }, - "main": "./worker/index.ts" -} -``` - - -::: + ### Call the API from the client @@ -276,38 +127,11 @@ If you click the button again, it will display the new `name` while preserving t With Vite and the Cloudflare plugin, you can iterate on the client and server parts of your app together, without losing UI state between edits. -### Build your application - -Run `npm run build` to build your application. - -```sh -npm run build -``` - -If you inspect the `dist` directory, you will see that it contains two subdirectories: - -- `client` - the client code that runs in the browser -- `cloudflare_vite_tutorial` - the Worker code alongside the output `wrangler.json` configuration file - -### Preview your application + -Run `npm run preview` to validate that your application runs as expected. - -```sh -npm run preview -``` - -This command will run your build output locally in the Workers runtime, closely matching its behaviour in production. - -### Deploy to Cloudflare - -Run `npm exec wrangler deploy` to deploy your application to Cloudflare. - -```sh -npm exec wrangler deploy -``` + -This command will automatically use the output `wrangler.json` that was included in the build output. + ## Next steps diff --git a/src/content/partials/workers/vite-plugin/add-api-worker.mdx b/src/content/partials/workers/vite-plugin/add-api-worker.mdx new file mode 100644 index 00000000000..39e4cafd767 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/add-api-worker.mdx @@ -0,0 +1,56 @@ +--- +{} +--- + +import { WranglerConfig } from "~/components"; + +### Add your API Worker + +Create a `worker/index.ts` file with the following contents: + +```ts title="worker/index.ts" +export default { + fetch(request) { + const url = new URL(request.url); + + if (url.pathname.startsWith("/api/")) { + return Response.json({ + name: "Cloudflare", + }); + } + + return new Response(null, { status: 404 }); + }, +} satisfies ExportedHandler; +``` + +The Worker above will be invoked for any non-navigation request that does not match a static asset. +It returns a JSON response if the `pathname` starts with `/api/` and otherwise returns a `404` response. + +:::note +For top-level navigation requests, browsers send a `Sec-Fetch-Mode: navigate` header. +If this is present and the URL does not match a static asset, the `not_found_handling` behavior will be invoked rather than the Worker. +This implicit routing is the default behavior. + +If you would instead like to define the routes that invoke your Worker explicitly, you can provide an array of route patterns to [`run_worker_first`](/workers/static-assets/binding/#run_worker_first). +This opts out of interpreting the `Sec-Fetch-Mode` header. + + + +```jsonc +{ + "$schema": "./node_modules/wrangler/config-schema.json", + "name": "cloudflare-vite-tutorial", + "compatibility_date": "$today", + "assets": { + "not_found_handling": "single-page-application", + "run_worker_first": [ + "/api/*" + ] + }, + "main": "./worker/index.ts" +} +``` + + +::: diff --git a/src/content/partials/workers/vite-plugin/add-dependencies.mdx b/src/content/partials/workers/vite-plugin/add-dependencies.mdx new file mode 100644 index 00000000000..47b01898a3f --- /dev/null +++ b/src/content/partials/workers/vite-plugin/add-dependencies.mdx @@ -0,0 +1,9 @@ +--- +{} +--- + +import { PackageManagers } from "~/components"; + +### Add the Cloudflare dependencies + + diff --git a/src/content/partials/workers/vite-plugin/add-plugin-to-vite-config.mdx b/src/content/partials/workers/vite-plugin/add-plugin-to-vite-config.mdx new file mode 100644 index 00000000000..16be03acd82 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/add-plugin-to-vite-config.mdx @@ -0,0 +1,19 @@ +--- +{} +--- + +### Add the Cloudflare Vite plugin to your project + +In your `vite.config.ts`, add the Cloudflare Vite plugin after your framework plugin: + +```ts {3, 6} title="vite.config.ts" +import { defineConfig } from "vite"; +import react from "@vitejs/plugin-react"; +import { cloudflare } from "@cloudflare/vite-plugin"; + +export default defineConfig({ + plugins: [react(), cloudflare()], +}); +``` + +The Cloudflare Vite plugin does not require any configuration by default and will look for a `wrangler.jsonc`, `wrangler.json`, or `wrangler.toml` in the root of your application. diff --git a/src/content/partials/workers/vite-plugin/add-tsconfig-worker.mdx b/src/content/partials/workers/vite-plugin/add-tsconfig-worker.mdx new file mode 100644 index 00000000000..29c0097b932 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/add-tsconfig-worker.mdx @@ -0,0 +1,35 @@ +--- +{} +--- + +import { PackageManagers } from "~/components"; + +### Add Workers TypeScript types + + + +Create a `tsconfig.worker.json` that extends your Node TypeScript configuration and adds the Workers types: + +```jsonc title="tsconfig.worker.json" +{ + "extends": "./tsconfig.node.json", + "compilerOptions": { + "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.worker.tsbuildinfo", + "types": ["@cloudflare/workers-types/2023-07-01", "vite/client"], + }, + "include": ["worker"], +} +``` + +Then add a reference to this new configuration in your root `tsconfig.json`: + +```jsonc {6} title="tsconfig.json" +{ + "files": [], + "references": [ + { "path": "./tsconfig.app.json" }, + { "path": "./tsconfig.node.json" }, + { "path": "./tsconfig.worker.json" }, + ], +} +``` diff --git a/src/content/partials/workers/vite-plugin/add-worker-config.mdx b/src/content/partials/workers/vite-plugin/add-worker-config.mdx new file mode 100644 index 00000000000..4f75ae828e6 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/add-worker-config.mdx @@ -0,0 +1,27 @@ +--- +{} +--- + +import { WranglerConfig } from "~/components"; + +### Add the Worker entrypoint to your configuration + +Update your Wrangler configuration file to add a `main` field that points to your Worker entrypoint: + + + +```jsonc +{ + "$schema": "./node_modules/wrangler/config-schema.json", + "name": "my-app", + "compatibility_date": "$today", + "assets": { + "not_found_handling": "single-page-application" + }, + "main": "./worker/index.ts" +} +``` + + + +The `main` field specifies the entry file for your Worker code. diff --git a/src/content/partials/workers/vite-plugin/build-app.mdx b/src/content/partials/workers/vite-plugin/build-app.mdx new file mode 100644 index 00000000000..6a821867544 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/build-app.mdx @@ -0,0 +1,16 @@ +--- +{} +--- + +### Build your application + +Run `npm run build` to build your application. + +```sh +npm run build +``` + +If you inspect the `dist` directory, you will see that it contains two subdirectories: + +- `client` - the client code that runs in the browser +- a directory containing your Worker code alongside the output `wrangler.json` configuration file diff --git a/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx b/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx new file mode 100644 index 00000000000..085f4307ad7 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx @@ -0,0 +1,41 @@ +--- +{} +--- + +import { WranglerConfig } from "~/components"; + +### Create your Worker config file + +Create a `wrangler.jsonc` file in the root of your project: + + + +```jsonc +{ + "$schema": "./node_modules/wrangler/config-schema.json", + "name": "my-app", + "compatibility_date": "$today", + "assets": { + "not_found_handling": "single-page-application" + } +} +``` + + + +The [`not_found_handling`](/workers/static-assets/routing/single-page-application/) value has been set to `single-page-application`. +This means that all not-found requests will serve the `index.html` file, which is required for React Router and other client-side routing solutions. + +With the Cloudflare plugin, the `assets` routing configuration is used in place of Vite's default behavior. +This ensures that your application's [routing configuration](/workers/static-assets/routing/) works the same way while developing as it does when deployed to production. + +Note that the [`directory`](/workers/static-assets/binding/#directory) field is not used when configuring assets with Vite. +The `directory` in the output configuration will automatically point to the client build output. +See [Static Assets](/workers/vite-plugin/reference/static-assets/) for more information. + +:::note +When using the Cloudflare Vite plugin, the Worker config (for example, `wrangler.jsonc`) that you provide is the input configuration file. +A separate output `wrangler.json` file is created when you run `vite build`. +This output file is a snapshot of your configuration at the time of the build and is modified to reference your build artifacts. +It is the configuration that is used for preview and deployment. +::: diff --git a/src/content/partials/workers/vite-plugin/deploy.mdx b/src/content/partials/workers/vite-plugin/deploy.mdx new file mode 100644 index 00000000000..b859c15b34e --- /dev/null +++ b/src/content/partials/workers/vite-plugin/deploy.mdx @@ -0,0 +1,13 @@ +--- +{} +--- + +### Deploy to Cloudflare + +Run `npm exec wrangler deploy` to deploy your application to Cloudflare. + +```sh +npm exec wrangler deploy +``` + +This command will automatically use the output `wrangler.json` that was included in the build output. diff --git a/src/content/partials/workers/vite-plugin/preview-app.mdx b/src/content/partials/workers/vite-plugin/preview-app.mdx new file mode 100644 index 00000000000..303cf35a206 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/preview-app.mdx @@ -0,0 +1,13 @@ +--- +{} +--- + +### Preview your application + +Run `npm run preview` to validate that your application runs as expected. + +```sh +npm run preview +``` + +This command will run your build output locally in the Workers runtime, closely matching its behavior in production. diff --git a/src/content/partials/workers/vite-plugin/run-dev-server.mdx b/src/content/partials/workers/vite-plugin/run-dev-server.mdx new file mode 100644 index 00000000000..66642356159 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/run-dev-server.mdx @@ -0,0 +1,14 @@ +--- +{} +--- + +import { PackageManagers } from "~/components"; + +### Run the development server + +Run your framework's development command to start the Vite development server and verify that your application is working as expected. + + + +For a purely front-end application, you could now build, preview, and deploy your application. +The following sections will show you how to go further and add an API Worker. diff --git a/src/content/partials/workers/vite-plugin/update-gitignore.mdx b/src/content/partials/workers/vite-plugin/update-gitignore.mdx new file mode 100644 index 00000000000..217b0a2989f --- /dev/null +++ b/src/content/partials/workers/vite-plugin/update-gitignore.mdx @@ -0,0 +1,13 @@ +--- +{} +--- + +### Update the `.gitignore` file + +When developing Workers, additional files are used and/or generated that should not be stored in Git. +Add the following lines to your `.gitignore` file: + +```txt title=".gitignore" +.wrangler +.dev.vars* +``` From 147b9eabe2424d4e2ac84f4c39eca537b3a5e027 Mon Sep 17 00:00:00 2001 From: Thomas Gauvin <35609369+thomasgauvin@users.noreply.github.com> Date: Sun, 7 Jun 2026 09:44:19 -0400 Subject: [PATCH 2/3] [Workers] Address review comments: fix description, imports, style guide violations, and use toml in WranglerConfig --- .../framework-guides/web-apps/react.mdx | 11 +++----- .../docs/workers/vite-plugin/tutorial.mdx | 2 +- .../workers/vite-plugin/add-api-worker.mdx | 25 ++++++++----------- .../workers/vite-plugin/add-worker-config.mdx | 19 +++++++------- .../workers/vite-plugin/build-app.mdx | 14 +++++------ .../vite-plugin/create-wrangler-config.mdx | 20 +++++++-------- .../partials/workers/vite-plugin/deploy.mdx | 9 ++++--- .../workers/vite-plugin/preview-app.mdx | 9 ++++--- 8 files changed, 50 insertions(+), 59 deletions(-) diff --git a/src/content/docs/workers/framework-guides/web-apps/react.mdx b/src/content/docs/workers/framework-guides/web-apps/react.mdx index e76a723d554..61ef0311129 100644 --- a/src/content/docs/workers/framework-guides/web-apps/react.mdx +++ b/src/content/docs/workers/framework-guides/web-apps/react.mdx @@ -4,15 +4,12 @@ title: React + Vite sidebar: order: 1 tags: ["spa"] -description: Create a React application and deploy it to Cloudflare Workers with Workers Assets. +description: Create a new React + Vite application or deploy an existing one to Cloudflare Workers with Workers Assets. products: - workers --- import { - Badge, - Description, - InlineBadge, Render, PackageManagers, Details, @@ -52,7 +49,7 @@ This guide shows you how to deploy a React + Vite application to Cloudflare Work args="my-react-app --framework=react" />
- Below is a simplified file tree of the project. + The following is a simplified file tree of the project. - my-react-app - src/ @@ -104,7 +101,7 @@ If you already have a React + Vite application, you can adapt it to deploy to Cl 1. **Navigate to your project directory** - Open your existing React + Vite project in your editor of choice. If you don't have one yet, scaffold a new project with Vite first: + Open your existing React + Vite project in your editor of choice. If you do not have one yet, scaffold a new project with Vite first: -### Add an API Worker to an existing project +## Add an API Worker to an existing project If you want to add an API Worker to your existing React + Vite project, follow these additional steps: diff --git a/src/content/docs/workers/vite-plugin/tutorial.mdx b/src/content/docs/workers/vite-plugin/tutorial.mdx index dc5d022c699..fb57f9a7559 100644 --- a/src/content/docs/workers/vite-plugin/tutorial.mdx +++ b/src/content/docs/workers/vite-plugin/tutorial.mdx @@ -5,7 +5,7 @@ title: Tutorial - React SPA with an API sidebar: order: 2 description: Create a React SPA with an API Worker using the Vite plugin -reviewed: 2025-04-04 +reviewed: 2026-06-07 products: - workers --- diff --git a/src/content/partials/workers/vite-plugin/add-api-worker.mdx b/src/content/partials/workers/vite-plugin/add-api-worker.mdx index 39e4cafd767..e79aaa157c6 100644 --- a/src/content/partials/workers/vite-plugin/add-api-worker.mdx +++ b/src/content/partials/workers/vite-plugin/add-api-worker.mdx @@ -24,7 +24,7 @@ export default { } satisfies ExportedHandler; ``` -The Worker above will be invoked for any non-navigation request that does not match a static asset. +The Worker defined in the preceding code block will be invoked for any non-navigation request that does not match a static asset. It returns a JSON response if the `pathname` starts with `/api/` and otherwise returns a `404` response. :::note @@ -37,19 +37,16 @@ This opts out of interpreting the `Sec-Fetch-Mode` header. -```jsonc -{ - "$schema": "./node_modules/wrangler/config-schema.json", - "name": "cloudflare-vite-tutorial", - "compatibility_date": "$today", - "assets": { - "not_found_handling": "single-page-application", - "run_worker_first": [ - "/api/*" - ] - }, - "main": "./worker/index.ts" -} +```toml +$schema = "./node_modules/wrangler/config-schema.json" +name = "cloudflare-vite-tutorial" +compatibility_date = "$today" + +[assets] +not_found_handling = "single-page-application" +run_worker_first = ["/api/*"] + +main = "./worker/index.ts" ``` diff --git a/src/content/partials/workers/vite-plugin/add-worker-config.mdx b/src/content/partials/workers/vite-plugin/add-worker-config.mdx index 4f75ae828e6..1938a4e97c9 100644 --- a/src/content/partials/workers/vite-plugin/add-worker-config.mdx +++ b/src/content/partials/workers/vite-plugin/add-worker-config.mdx @@ -10,16 +10,15 @@ Update your Wrangler configuration file to add a `main` field that points to you -```jsonc -{ - "$schema": "./node_modules/wrangler/config-schema.json", - "name": "my-app", - "compatibility_date": "$today", - "assets": { - "not_found_handling": "single-page-application" - }, - "main": "./worker/index.ts" -} +```toml +$schema = "./node_modules/wrangler/config-schema.json" +name = "my-app" +compatibility_date = "$today" + +[assets] +not_found_handling = "single-page-application" + +main = "./worker/index.ts" ``` diff --git a/src/content/partials/workers/vite-plugin/build-app.mdx b/src/content/partials/workers/vite-plugin/build-app.mdx index 6a821867544..bcfa6fbf420 100644 --- a/src/content/partials/workers/vite-plugin/build-app.mdx +++ b/src/content/partials/workers/vite-plugin/build-app.mdx @@ -1,16 +1,14 @@ --- {} + --- -### Build your application +import { PackageManagers } from "~/components"; -Run `npm run build` to build your application. +### Build your application -```sh -npm run build -``` +Run the build command to build your application. -If you inspect the `dist` directory, you will see that it contains two subdirectories: + -- `client` - the client code that runs in the browser -- a directory containing your Worker code alongside the output `wrangler.json` configuration file +The `dist` directory will contain your client build output in the `client` subdirectory and your Worker code alongside the output `wrangler.json` configuration file. diff --git a/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx b/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx index 085f4307ad7..2a1364a1c4c 100644 --- a/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx +++ b/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx @@ -10,15 +10,13 @@ Create a `wrangler.jsonc` file in the root of your project: -```jsonc -{ - "$schema": "./node_modules/wrangler/config-schema.json", - "name": "my-app", - "compatibility_date": "$today", - "assets": { - "not_found_handling": "single-page-application" - } -} +```toml +$schema = "./node_modules/wrangler/config-schema.json" +name = "my-app" +compatibility_date = "$today" + +[assets] +not_found_handling = "single-page-application" ``` @@ -29,9 +27,9 @@ This means that all not-found requests will serve the `index.html` file, which i With the Cloudflare plugin, the `assets` routing configuration is used in place of Vite's default behavior. This ensures that your application's [routing configuration](/workers/static-assets/routing/) works the same way while developing as it does when deployed to production. -Note that the [`directory`](/workers/static-assets/binding/#directory) field is not used when configuring assets with Vite. +The [`directory`](/workers/static-assets/binding/#directory) field is not used when configuring assets with Vite. The `directory` in the output configuration will automatically point to the client build output. -See [Static Assets](/workers/vite-plugin/reference/static-assets/) for more information. +Refer to [Static Assets](/workers/vite-plugin/reference/static-assets/) for more information. :::note When using the Cloudflare Vite plugin, the Worker config (for example, `wrangler.jsonc`) that you provide is the input configuration file. diff --git a/src/content/partials/workers/vite-plugin/deploy.mdx b/src/content/partials/workers/vite-plugin/deploy.mdx index b859c15b34e..ad059698cac 100644 --- a/src/content/partials/workers/vite-plugin/deploy.mdx +++ b/src/content/partials/workers/vite-plugin/deploy.mdx @@ -1,13 +1,14 @@ --- {} + --- +import { PackageManagers } from "~/components"; + ### Deploy to Cloudflare -Run `npm exec wrangler deploy` to deploy your application to Cloudflare. +Run the deploy command to deploy your application to Cloudflare. -```sh -npm exec wrangler deploy -``` + This command will automatically use the output `wrangler.json` that was included in the build output. diff --git a/src/content/partials/workers/vite-plugin/preview-app.mdx b/src/content/partials/workers/vite-plugin/preview-app.mdx index 303cf35a206..53da3eda44d 100644 --- a/src/content/partials/workers/vite-plugin/preview-app.mdx +++ b/src/content/partials/workers/vite-plugin/preview-app.mdx @@ -1,13 +1,14 @@ --- {} + --- +import { PackageManagers } from "~/components"; + ### Preview your application -Run `npm run preview` to validate that your application runs as expected. +Run the preview command to validate that your application runs as expected. -```sh -npm run preview -``` + This command will run your build output locally in the Workers runtime, closely matching its behavior in production. From c9360e5c817f178c413cd7d759390c6295b9fe18 Mon Sep 17 00:00:00 2001 From: Brendan Irvine-Broque Date: Sat, 5 Sep 2026 09:46:48 -0700 Subject: [PATCH 3/3] [Workers] Fix Vite Wrangler configuration examples --- src/content/partials/workers/vite-plugin/add-api-worker.mdx | 5 ++--- .../partials/workers/vite-plugin/add-worker-config.mdx | 4 +--- .../partials/workers/vite-plugin/create-wrangler-config.mdx | 1 - 3 files changed, 3 insertions(+), 7 deletions(-) diff --git a/src/content/partials/workers/vite-plugin/add-api-worker.mdx b/src/content/partials/workers/vite-plugin/add-api-worker.mdx index e79aaa157c6..ec94c2f71a5 100644 --- a/src/content/partials/workers/vite-plugin/add-api-worker.mdx +++ b/src/content/partials/workers/vite-plugin/add-api-worker.mdx @@ -38,16 +38,15 @@ This opts out of interpreting the `Sec-Fetch-Mode` header. ```toml -$schema = "./node_modules/wrangler/config-schema.json" name = "cloudflare-vite-tutorial" compatibility_date = "$today" +main = "./worker/index.ts" [assets] not_found_handling = "single-page-application" run_worker_first = ["/api/*"] - -main = "./worker/index.ts" ``` + ::: diff --git a/src/content/partials/workers/vite-plugin/add-worker-config.mdx b/src/content/partials/workers/vite-plugin/add-worker-config.mdx index 1938a4e97c9..e5a32222bd1 100644 --- a/src/content/partials/workers/vite-plugin/add-worker-config.mdx +++ b/src/content/partials/workers/vite-plugin/add-worker-config.mdx @@ -11,14 +11,12 @@ Update your Wrangler configuration file to add a `main` field that points to you ```toml -$schema = "./node_modules/wrangler/config-schema.json" name = "my-app" compatibility_date = "$today" +main = "./worker/index.ts" [assets] not_found_handling = "single-page-application" - -main = "./worker/index.ts" ``` diff --git a/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx b/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx index 2a1364a1c4c..d190881dcf5 100644 --- a/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx +++ b/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx @@ -11,7 +11,6 @@ Create a `wrangler.jsonc` file in the root of your project: ```toml -$schema = "./node_modules/wrangler/config-schema.json" name = "my-app" compatibility_date = "$today"