← Cloudflare Workers / workers / vite-plugin

Tutoriál - React SPA s API

Tento návod vás provede kroky potřebnými k úpravě projektu Vite tak, aby využíval Cloudflare Vite plugin. Většinu obsahu lze použít i při úpravě existujících projektů Vite a u jiných front-end frameworků než React.

V tomto tutoriálu vytvoříte React SPA, kterou bude možné nasadit jako Worker se statickými assety. Poté přidáte API Worker, ke kterému bude možné přistupovat z front-end kódu. Aplikaci budete vyvíjet, sestavovat a náhledovat pomocí Vite a nakonec ji nasadíte na Cloudflare.

Začněte vytvořením projektu React TypeScript pomocí Vite.

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

Dále otevřete cloudflare-vite-tutorial adresář v editoru dle vlastního výběru.

npm i -D @cloudflare/vite-plugin wrangler

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

export default defineConfig({
	plugins: [react(), cloudflare()],
});

Plugin Cloudflare pro Vite ve výchozím nastavení nevyžaduje žádnou konfiguraci a bude hledat wrangler.jsonc, wrangler.json nebo wrangler.toml v kořenovém adresáři vaší aplikace.

Viz Referenční dokumentace API pro možnosti konfigurace.

{
	"$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 hodnota byla nastavena na single-page-application. Znamená to, že všechny požadavky s výsledkem not found obslouží index.html soubor. S pluginem Cloudflare assets konfigurace směrování se použije místo výchozího chování Vite. Tím se zajistí, že aplikace bude mít konfigurace směrování funguje stejně během vývoje jako po nasazení do produkce.

Upozorňujeme, že directory pole se při konfiguraci assetů pomocí Vite nepoužívá. directory v konfiguraci výstupu bude automaticky odkazovat na výstup sestavení klienta. Viz Static Assets s dalšími informacemi.

Při vývoji Workerů se používají nebo generují další soubory, které by neměly být ukládány do gitu. Přidejte do svého .gitignore soubor:

.wrangler
.dev.vars*

Spustit npm run dev pro spuštění vývojového serveru Vite a ověření, že vaše aplikace funguje podle očekávání.

Pro čistě frontendovou aplikaci byste nyní mohli sestavit (npm run build), zobrazit náhled (npm run preview), a nasadit (npm exec wrangler deploy) vaší aplikace. Tento tutoriál vám ale ukáže, jak jít o krok dál a přidat API Worker.

npm i -D @cloudflare/workers-types

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

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

{
	"$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 pole určuje vstupní soubor pro kód vašeho Workeru.

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;

Výše uvedený Worker se vyvolá pro jakýkoli non-navigation požadavek, který neodpovídá žádnému statickému assetu. Vrátí JSON odpověď, pokud pathname začíná na /api/ a jinak vrátí 404 odpověď.

Upravit src/App.tsx tak, aby obsahovala další tlačítko, které volá API a nastavuje nějaký stav:

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;

Pokud nyní kliknete na tlačítko, zobrazí se 'Name from API is: Cloudflare'.

Zvyšte hodnotu čítače a aktualizujte tak stav aplikace v prohlížeči. Dále upravte api/index.ts změnou name se vrací do 'Cloudflare Workers'. Pokud tlačítko kliknete znovu, zobrazí se nový name při zachování dříve nastavené hodnoty počítadla.

S Vite a Cloudflare pluginem můžete upravovat klientskou i serverovou část aplikace současně, aniž byste mezi jednotlivými úpravami ztráceli stav UI.

Spustit npm run build pro sestavení vaší aplikace.

npm run build

Pokud prozkoumáte dist adresáři uvidíte, že obsahuje dva podadresáře:

• client - klientský kód, který běží v prohlížeči
• cloudflare_vite_tutorial - kód Workeru vedle výstupu wrangler.json konfigurační soubor

Spustit npm run preview pro ověření, že vaše aplikace běží podle očekávání.

npm run preview

Tento příkaz spustí výstup vašeho sestavení lokálně v runtime Workers, přičemž se chování bude velmi blížit produkčnímu prostředí.

Spustit npm exec wrangler deploy pro nasazení vaší aplikace na Cloudflare.

npm exec wrangler deploy

Tento příkaz automaticky použije výstup wrangler.json který byl součástí výstupu sestavení.

V tomto tutoriálu jsme vytvořili SPA, kterou bylo možné nasadit jako Worker se statickými assety. Poté jsme přidali API Worker, ke kterému bylo možné přistupovat z front-end kódu. Nakonec jsme na Cloudflare nasadili jak klientskou, tak serverovou část aplikace.

Mezi možné další kroky patří:

• Přidání vazby na jinou službu Cloudflare, například na KV namespace nebo databáze D1
• Rozšíření API o další trasy
• Pomocí knihovny, jako je Hono ↗ nebo tRPC ↗, ve vašem API Workeru