React + Vite

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

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

Develop locally with the Cloudflare Vite plugin

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

npm run dev

yarn run dev

pnpm run dev

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.

npm run deploy

yarn run deploy

pnpm run deploy

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:

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.

Add the Cloudflare Vite plugin

Add the Cloudflare dependencies

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:

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 for your Worker. The client environment keeps its existing source map settings.

Refer to the API reference for configuration options.

Add a Wrangler configuration file

Create your Worker config file

Create a wrangler.jsonc file in the root of your project:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-app",
  // Set this to today's date
  "compatibility_date": "2026-11-02",
  "assets": {
    "not_found_handling": "single-page-application"
  }
}

name = "my-app"
# Set this to today's date
compatibility_date = "2026-11-02"

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

The not_found_handling 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 works the same way while developing as it does when deployed to production.

The 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 for more information.

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:

.wrangler
.dev.vars*

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.

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.

Build and deploy your project

Build your application

Run the build command to build your application.

npm run build

yarn run build

pnpm run build

The dist directory will contain your client build output in the client subdirectory and your Worker code alongside the output wrangler.json configuration file.

Preview your application

Run the preview command to validate that your application runs as expected.

npm run preview

yarn run preview

pnpm run preview

This command will run your build output locally in the Workers runtime, closely matching its behavior in production.

Deploy to Cloudflare

Run the deploy command to deploy your application to Cloudflare.

npx wrangler deploy

yarn wrangler deploy

pnpm wrangler deploy

This command will automatically use the output wrangler.json that was included in the build output.

Configure TypeScript for your Worker code

Add Workers TypeScript types

npm i -D @cloudflare/workers-types

yarn add -D @cloudflare/workers-types

pnpm add -D @cloudflare/workers-types

bun add -d @cloudflare/workers-types

Create a tsconfig.worker.json that extends your Node TypeScript configuration and adds the Workers types:

{
	"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:

{
	"files": [],
	"references": [
		{ "path": "./tsconfig.app.json" },
		{ "path": "./tsconfig.node.json" },
		{ "path": "./tsconfig.worker.json" },
	],
}

Add the Worker entrypoint to your configuration

Add the Worker entrypoint to your configuration

Update your Wrangler configuration file to add a main field that points to your Worker entrypoint:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-app",
  // Set this to today's date
  "compatibility_date": "2026-11-02",
  "main": "./worker/index.ts",
  "upload_source_maps": true,
  "assets": {
    "not_found_handling": "single-page-application"
  }
}

name = "my-app"
# Set this to today's date
compatibility_date = "2026-11-02"
main = "./worker/index.ts"
upload_source_maps = true

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

The main field specifies the entry file for your Worker code.

Add your API Worker

Add your API Worker

Create a worker/index.ts file with the following contents:

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.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "cloudflare-vite-tutorial",
  // Set this to today's date
  "compatibility_date": "2026-11-02",
  "main": "./worker/index.ts",
  "upload_source_maps": true,
  "assets": {
    "not_found_handling": "single-page-application",
    "run_worker_first": [
      "/api/*"
    ]
  }
}

name = "cloudflare-vite-tutorial"
# Set this to today's date
compatibility_date = "2026-11-02"
main = "./worker/index.ts"
upload_source_maps = true

[assets]
not_found_handling = "single-page-application"
run_worker_first = ["/api/*"]

Call the API from the client

You can now call your API from your React components. For example, in src/App.tsx:

import { useState } from "react";

function App() {
	const [name, setName] = useState("unknown");

	return (
		<div className="card">
			<button
				onClick={() => {
					fetch("/api/")
						.then((res) => res.json() as Promise<{ name: string }>)
						.then((data) => setName(data.name));
				}}
			>
				Name from API is: {name}
			</button>
		</div>
	);
}

export default App;