React + Vite

Last updated Sep 5, 2026 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 for lightning-fast development.

npmyarnpnpm

npm create cloudflare@latest -- my-react-app --framework=react

yarn create cloudflare my-react-app --framework=react

pnpm create cloudflare@latest my-react-app --framework=react

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.

1. Create a new project with the create-cloudflare CLI (C3)npmyarnpnpm

   npm create cloudflare@latest -- my-react-app --framework=react
   ```

yarn create cloudflare my-react-app --framework=react ```

   pnpm create cloudflare@latest my-react-app --framework=react
   ```

<details><summary>

How is this project set up?</summary>

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

<code>wrangler.jsonc</code> is your <a href="https://developers.cloudflare.com/workers/wrangler/configuration/">Wrangler configuration file</a>. In this file:
   - <code>main</code> points to <code>worker/index.ts</code>. This is your Worker, which is going to act as your backend API.
   - <code>assets.not_found_handling</code> is set to <code>single-page-application</code>, 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 <a href="https://developers.cloudflare.com/workers/runtime-apis/bindings/">bindings</a>.

<code>vite.config.ts</code> is set up to use the <a href="https://developers.cloudflare.com/workers/vite-plugin/">Cloudflare Vite plugin</a>. This runs your Worker in the Cloudflare Workers runtime, ensuring your local development environment is as close to production as possible.

<code>worker/index.ts</code> is your backend API, which contains a single endpoint, <code>/api/</code>, that returns a text response. At <code>src/App.tsx</code>, your React app calls this endpoint to get a message back and displays this.</details>

2. **Develop locally with the [Cloudflare Vite plugin](https://developers.cloudflare.com/workers/vite-plugin/)**

After creating your project, run the following command in your project directory to start a local development server.npmyarnpnpm

npm run dev ```

   yarn run dev
   ```

pnpm run dev ```

<details><summary>

What's happening in local development?</summary>

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, <code>vite.config.ts</code> 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.</details>

1. Deploy your project

Your project can be deployed to a *.workers.dev subdomain or a Custom Domain, from your own machine or from any CI/CD system, including Cloudflare's own Workers Builds.

The following command will build and deploy your project. If you are using CI, ensure you update your "deploy command" configuration appropriately.npmyarnpnpm

   npm run deploy
   ```

yarn run deploy ```

   pnpm run deploy
   ```

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:npmyarnpnpm

npm create vite@latest -- my-react-app --template react-ts ```

   yarn create vite my-react-app --template react-ts
   ```

pnpm create vite@latest my-react-app --template react-ts ```

Next, open the my-react-app directory in your editor of choice. 2. Add the Cloudflare Vite plugin### Add the Cloudflare dependencies npmyarnpnpmbun

   npm i -D @cloudflare/vite-plugin wrangler
   ```

yarn add -D @cloudflare/vite-plugin wrangler ```

   pnpm add -D @cloudflare/vite-plugin wrangler
   ```

bun add -d @cloudflare/vite-plugin wrangler ```

Add the Cloudflare Vite plugin to your project In your vite.config.ts, add the Cloudflare Vite plugin after your framework plugin:

vite.config.tsts

   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react";
   import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
    plugins: [react(), cloudflare({ viteEnvironment: { name: "worker" } })],
    environments: {
        worker: { build: { sourcemap: true } },
    },
   });
   ```

The Cloudflare Vite plugin looks for a `wrangler.jsonc`, `wrangler.json`, or `wrangler.toml` in the root of your application.

The `worker` environment generates [source maps](https://developers.cloudflare.com/workers/observability/source-maps/) for your Worker. The client environment keeps its existing source map settings.

Refer to the [API reference](https://developers.cloudflare.com/workers/vite-plugin/reference/api/) for configuration options.
3. **Add a Wrangler configuration file**### 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",
     // Set this to today's date
     "compatibility_date": "2026-10-27",
     "assets": {
       "not_found_handling": "single-page-application"
     }
   }
   ```

```toml
   name = "my-app"
   # Set this to today's date
   compatibility_date = "2026-10-27"

[assets]
   not_found_handling = "single-page-application"
   ```

The [`not_found_handling`](https://developers.cloudflare.com/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](https://developers.cloudflare.com/workers/static-assets/routing/) works the same way while developing as it does when deployed to production.

The [`directory`](https://developers.cloudflare.com/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](https://developers.cloudflare.com/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.
4. **Update the `.gitignore` file**### 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:

*.gitignoretxt*

```txt
   .wrangler
   .dev.vars*
   ```

5. **Develop locally**### 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.npmyarnpnpm

npm run dev ```

   yarn run dev
   ```

pnpm run dev ```

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. 6. Build and deploy your project### Build your application Run the build command to build your application.npmyarnpnpm