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 169d6985855..f6a73bdcd16 100644 --- a/src/content/docs/workers/framework-guides/web-apps/react.mdx +++ b/src/content/docs/workers/framework-guides/web-apps/react.mdx @@ -4,22 +4,28 @@ 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, 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, Hono 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/vite-react-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. -
+ The following 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 do not 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 +201,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 c5b6e9446a9..fb57f9a7559 100644 --- a/src/content/docs/workers/vite-plugin/tutorial.mdx +++ b/src/content/docs/workers/vite-plugin/tutorial.mdx @@ -5,12 +5,12 @@ 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 --- -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/2023-07-01", "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..e79aaa157c6 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/add-api-worker.mdx @@ -0,0 +1,53 @@ +--- +{} +--- + +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 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 +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. + + + +```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-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..1938a4e97c9 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/add-worker-config.mdx @@ -0,0 +1,26 @@ +--- +{} +--- + +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: + + + +```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" +``` + + + +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..bcfa6fbf420 --- /dev/null +++ b/src/content/partials/workers/vite-plugin/build-app.mdx @@ -0,0 +1,14 @@ +--- +{} + +--- + +import { PackageManagers } from "~/components"; + +### Build your application + +Run the build command to build your application. + + + +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 new file mode 100644 index 00000000000..2a1364a1c4c --- /dev/null +++ b/src/content/partials/workers/vite-plugin/create-wrangler-config.mdx @@ -0,0 +1,39 @@ +--- +{} +--- + +import { WranglerConfig } from "~/components"; + +### Create your Worker config file + +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" + +[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. + +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. +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. +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..ad059698cac --- /dev/null +++ b/src/content/partials/workers/vite-plugin/deploy.mdx @@ -0,0 +1,14 @@ +--- +{} + +--- + +import { PackageManagers } from "~/components"; + +### Deploy to Cloudflare + +Run the deploy command to deploy your application to Cloudflare. + + + +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..53da3eda44d --- /dev/null +++ b/src/content/partials/workers/vite-plugin/preview-app.mdx @@ -0,0 +1,14 @@ +--- +{} + +--- + +import { PackageManagers } from "~/components"; + +### Preview your application + +Run the preview command to validate that your application runs as expected. + + + +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* +```