← Cloudflare Workers / workers / vite-plugin

Руководство - React SPA с API

Это руководство проведет вас через шаги, необходимые для перехода проекта Vite на плагин Cloudflare Vite. Большую часть материала можно применить и при адаптации существующих проектов Vite, а также фронтенд-фреймворков, отличных от React.

Введение

В этом руководстве вы создадите React SPA, которое можно развернуть как Worker со статическими ресурсами. Затем вы добавите API Worker, доступный из клиентского кода. Вы разработаете, соберёте и просмотрите приложение с помощью Vite, а затем развернёте его в Cloudflare.

Настройка и конфигурирование React SPA

Создайте каркас проекта Vite

Для начала создайте проект React TypeScript с помощью Vite.

npm create vite@latest -- cloudflare-vite-tutorial --template react-ts

Затем откройте cloudflare-vite-tutorial каталог в редакторе по вашему выбору.

Добавление зависимостей Cloudflare

npm i -D @cloudflare/vite-plugin wrangler

Добавление плагина в конфигурацию Vite

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()],
});

Плагин Cloudflare для Vite по умолчанию не требует настройки и будет искать wrangler.jsonc, wrangler.json или wrangler.toml в корне вашего приложения.

См. Справочник по API для параметров настройки.

Создание файла конфигурации Worker

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "cloudflare-vite-tutorial",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"assets": {
		"not_found_handling": "single-page-application"
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "cloudflare-vite-tutorial"
# Set this to today's date
compatibility_date = "2026-08-28"

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

not_found_handling значение установлено в single-page-application. Это означает, что на все запросы, для которых ничего не найдено, будет отдаваться index.html файле. С плагином Cloudflare assets конфигурация маршрутизации используется вместо стандартного поведения Vite. Это гарантирует, что конфигурация маршрутизации работает одинаково как при разработке, так и в производственной среде после развёртывания.

Обратите внимание на directory поле не используется при настройке ресурсов с помощью Vite. directory в конфигурации output будет автоматически указывать на выходные файлы сборки клиента. См. Static Assets, где это описано подробнее.

Обновите файл .gitignore

При разработке Workers используются и/или создаются дополнительные файлы, которые не следует хранить в git. Добавьте следующие строки в .gitignore файле:

.gitignore

.wrangler
.dev.vars*

Запустите сервер разработки

Запустите npm run dev чтобы запустить сервер разработки Vite и убедиться, что приложение работает как ожидается.

Для исключительно клиентского (frontend) приложения теперь можно собрать (npm run build), предварительный просмотр (npm run preview), и развернуть (npm exec wrangler deploy) ваше приложение. Однако в этом руководстве мы пойдём дальше и покажем, как добавить API Worker.

Добавление API Worker

Настройте TypeScript для кода Worker

npm i -D @cloudflare/workers-types

tsconfig.worker.json

{
	"extends": "./tsconfig.node.json",
	"compilerOptions": {
		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.worker.tsbuildinfo",
		"types": ["@cloudflare/workers-types", "vite/client"],
	},
	"include": ["worker"],
}

tsconfig.json

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

Добавление в конфигурацию Worker

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "cloudflare-vite-tutorial",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"assets": {
		"not_found_handling": "single-page-application"
	},
	"main": "./worker/index.ts"
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "cloudflare-vite-tutorial"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./worker/index.ts"

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

main поле указывает файл входной точки для кода вашего Worker.

Добавление API Worker

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;

Worker выше будет вызываться для любого запроса, не связанного с навигацией, который не соответствует статическому ресурсу. Он возвращает JSON-ответ, если pathname начинается с /api/ и в противном случае вернуть 404 ответ.

Примечание

Для запросов навигации верхнего уровня браузеры отправляют Sec-Fetch-Mode: navigate заголовок. Если этот заголовок присутствует и URL не совпадает ни с одним статическим ассетом, not_found_handling поведение будет вызвано вместо Worker. Эта неявная маршрутизация является поведением по умолчанию.

Если вы хотите вместо этого явно задать маршруты, вызывающие ваш Worker, передайте массив шаблонов маршрутов в run_worker_first. Это отключает интерпретацию Sec-Fetch-Mode заголовок.

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

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "cloudflare-vite-tutorial"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./worker/index.ts"

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

Вызов API с клиента

Изменить src/App.tsx чтобы добавить дополнительную кнопку, которая вызывает API и задает некоторое состояние:

src/App.tsx

import { useState } from "react";
import reactLogo from "./assets/react.svg";
import viteLogo from "/vite.svg";
import "./App.css";

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

	return (
		<>
			<div>
				<a href="https://vite.dev" target="_blank">
					<img src={viteLogo} className="logo" alt="Vite logo" />
				</a>
				<a href="https://react.dev" target="_blank">
					<img src={reactLogo} className="logo react" alt="React logo" />
				</a>
			</div>
			<h1>Vite + React</h1>
			<div className="card">
				<button
					onClick={() => setCount((count) => count + 1)}
					aria-label="increment"
				>
					count is {count}
				</button>
				<p>
					Edit <code>src/App.tsx</code> and save to test HMR
				</p>
			</div>
			<div className="card">
				<button
					onClick={() => {
						fetch("/api/")
							.then((res) => res.json() as Promise<{ name: string }>)
							.then((data) => setName(data.name));
					}}
					aria-label="get name"
				>
					Name from API is: {name}
				</button>
				<p>
					Edit <code>api/index.ts</code> to change the name
				</p>
			</div>
			<p className="read-the-docs">
				Click on the Vite and React logos to learn more
			</p>
		</>
	);
}

export default App;

Теперь, если нажать кнопку, отобразится 'Name from API is: Cloudflare'.

Увеличьте счётчик, чтобы обновить состояние приложения в браузере. Затем отредактируйте api/index.ts изменив name выполняется возврат в 'Cloudflare Workers'. Если вы нажмёте кнопку ещё раз, отобразится новый name сохраняя ранее установленное значение счётчика.

С Vite и плагином Cloudflare вы можете одновременно дорабатывать клиентскую и серверную части приложения, не теряя состояние UI между правками.

Соберите приложение

Запустите npm run build чтобы собрать ваше приложение.

npm run build

Если вы проверите dist каталог, вы увидите, что он содержит два подкаталога:

client - клиентский код, который выполняется в браузере
cloudflare_vite_tutorial - код Worker вместе с результатом сборки wrangler.json файл конфигурации

Откройте предпросмотр приложения

Запустите npm run preview чтобы убедиться, что приложение работает как ожидается.

npm run preview

Эта команда запустит результат сборки локально в среде выполнения Workers, максимально точно повторяя поведение в продакшене.

Deploy to Cloudflare

Запустите npm exec wrangler deploy чтобы развернуть ваше приложение в Cloudflare.

npm exec wrangler deploy

Эта команда автоматически использует вывод wrangler.json который был включён в результат сборки.

Следующие шаги

В этом руководстве мы создали SPA, которое можно развернуть как Worker со статическими ресурсами. Затем мы добавили API Worker, доступный из клиентского кода. Наконец, мы развернули клиентскую и серверную части приложения в Cloudflare.

Возможные дальнейшие шаги:

Добавление привязки к другому сервису Cloudflare, например к Пространство имён KV или База данных D1
Расширение API за счёт дополнительных маршрутов
Использование библиотеки, например Hono ↗ или tRPC ↗, в вашем API Worker