תיעוד 282

מדריך: SPA של React עם API

המדריך הזה מעביר אתכם דרך השלבים הדרושים כדי להתאים פרויקט Vite לשימוש בתוסף Vite של Cloudflare. חלק גדול מהתוכן מתאים גם להתאמה של פרויקטי Vite קיימים, ולמסגרות צד לקוח שאינן React.

הערה

אם אתם רוצים להתחיל אפליקציה חדשה עם תבנית שכבר מוגדרת עם Vite, React ותוסף Vite של Cloudflare, פנו אל מדריך מסגרת React. כדי ליצור Worker עצמאי, פנו אל התחלה.

#מבוא

במדריך הזה תיצרו SPA של React שאפשר לפרוס כ-Worker עם נכסים סטטיים. לאחר מכן תוסיפו Worker של API שאפשר לגשת אליו מקוד צד הלקוח. תפתחו, תבנו ותציגו את האפליקציה בתצוגה מקדימה באמצעות Vite, ולבסוף תפרסו ל-Cloudflare.

#הגדרה וקביעת תצורה של ה-SPA של React

#יצירת שלד לפרויקט Vite

התחילו ביצירת פרויקט React עם TypeScript באמצעות Vite.

npm

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

yarn

yarn create vite cloudflare-vite-tutorial --template react-ts

pnpm

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

לאחר מכן, פתחו את התיקייה cloudflare-vite-tutorial בעורך לבחירתכם.

#הוספת התלויות של Cloudflare

npm

npm i -D @cloudflare/vite-plugin wrangler

yarn

yarn add -D @cloudflare/vite-plugin wrangler

pnpm

pnpm add -D @cloudflare/vite-plugin wrangler

bun

bun add -d @cloudflare/vite-plugin wrangler

#הוספת תוסף Vite של Cloudflare לפרויקט

בקובץ vite.config.ts, הוסיפו את תוסף Vite של Cloudflare אחרי תוסף המסגרת:

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({ viteEnvironment: { name: "worker" } })],
	environments: {
		worker: { build: { sourcemap: true } },
	},
});

תוסף Vite של Cloudflare מחפש wrangler.jsonc, wrangler.json או wrangler.toml בשורש האפליקציה.

סביבת worker מייצרת מפות מקור עבור ה-Worker. סביבת הלקוח שומרת על הגדרות מפות המקור הקיימות שלה.

#יצירת קובץ התצורה של Worker

צרו קובץ wrangler.jsonc בשורש הפרויקט:

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

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

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

הערך not_found_handling הוגדר ל-single-page-application. המשמעות היא שכל הבקשות שלא נמצאו יגישו את הקובץ index.html, וזה נדרש עבור React Router ועבור פתרונות ניתוב אחרים בצד הלקוח.

עם התוסף של Cloudflare, תצורת הניתוב של assets משמשת במקום התנהגות ברירת המחדל של Vite. כך מובטח שתצורת הניתוב של האפליקציה פועלת באותו אופן בזמן פיתוח כמו כשהיא פרוסה לייצור.

השדה directory לא בשימוש כשמגדירים נכסים עם Vite. ה-directory בתצורת הפלט יצביע אוטומטית על פלט הבנייה של הלקוח. פנו אל נכסים סטטיים למידע נוסף.

הערה

כשמשתמשים בתוסף Vite של Cloudflare, תצורת ה-Worker שאתם מספקים (לדוגמה, wrangler.jsonc) היא קובץ תצורת הקלט. קובץ פלט נפרד בשם wrangler.json נוצר כשמריצים את vite build. קובץ הפלט הזה הוא צילום מצב של התצורה בזמן הבנייה, והוא משתנה כדי להפנות אל תוצרי הבנייה. זו התצורה שמשמשת לתצוגה מקדימה ולפריסה.

#עדכון הקובץ `.gitignore`

בפיתוח Workers נעשה שימוש בקבצים נוספים ו/או נוצרים קבצים נוספים שאין לאחסן ב-Git. הוסיפו את השורות הבאות לקובץ .gitignore:

.gitignore

.wrangler
.dev.vars*

#הרצת שרת הפיתוח

הריצו את פקודת הפיתוח של המסגרת כדי להפעיל את שרת הפיתוח של Vite ולוודא שהאפליקציה פועלת כמצופה.

npm

npm run dev

yarn

yarn run dev

pnpm

pnpm run dev

עבור אפליקציה שהיא רק צד לקוח, אפשר עכשיו לבנות, להציג בתצוגה מקדימה ולפרוס את האפליקציה. הסעיפים הבאים יראו איך להמשיך ולהוסיף Worker של API.

#הוספת Worker של API

#הוספת טיפוסי TypeScript של Workers

npm

npm i -D @cloudflare/workers-types

yarn

yarn add -D @cloudflare/workers-types

pnpm

pnpm add -D @cloudflare/workers-types

bun

bun add -d @cloudflare/workers-types

צרו קובץ tsconfig.worker.json שמרחיב את תצורת TypeScript של Node ומוסיף את טיפוסי Workers:

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"],
}

לאחר מכן הוסיפו הפניה לתצורה החדשה בקובץ tsconfig.json בשורש:

tsconfig.json

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

#הוספת נקודת הכניסה של Worker לתצורה

עדכנו את קובץ התצורה של Wrangler כדי להוסיף שדה main שמצביע על נקודת הכניסה של ה-Worker:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-app",
  // Set this to today's date
  "compatibility_date": "2026-10-12",
  "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-10-12"
main = "./worker/index.ts"
upload_source_maps = true

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

השדה main מציין את קובץ הכניסה של קוד ה-Worker.

#הוספת ה-API Worker

צרו קובץ worker/index.ts עם התוכן הבא:

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. אם הכותרת הזו קיימת והכתובת לא תואמת לנכס סטטי, תופעל ההתנהגות של 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-10-12",
  "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-10-12"
main = "./worker/index.ts"
upload_source_maps = true

[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 אפשר לפתח את חלקי הלקוח והשרת של האפליקציה יחד, בלי לאבד את מצב ממשק המשתמש בין עריכות.

#בניית האפליקציה

הריצו את פקודת הבנייה כדי לבנות את האפליקציה.

npm

npm run build

yarn

yarn run build

pnpm

pnpm run build

התיקייה dist תכיל את פלט הבנייה של הלקוח בתת התיקייה client, ואת קוד ה-Worker לצד קובץ התצורה wrangler.json של הפלט.

#תצוגה מקדימה של האפליקציה

הריצו את פקודת התצוגה המקדימה כדי לוודא שהאפליקציה רצה כמצופה.

npm

npm run preview

yarn

yarn run preview

pnpm

pnpm run preview

הפקודה הזו תריץ את פלט הבנייה באופן מקומי בסביבת הריצה של Workers, באופן שקרוב להתנהגות שלה בייצור.

#פריסה ל-Cloudflare

הריצו את פקודת הפריסה כדי לפרוס את האפליקציה ל-Cloudflare.

npm

npx wrangler deploy

yarn

yarn wrangler deploy

pnpm

pnpm wrangler deploy

הפקודה הזו תשתמש אוטומטית בקובץ הפלט wrangler.json שנכלל בפלט הבנייה.

#השלבים הבאים

במדריך הזה יצרנו SPA שאפשר לפרוס כ-Worker עם נכסים סטטיים. לאחר מכן הוספנו Worker של API שאפשר לגשת אליו מקוד צד הלקוח. לבסוף, פרסנו גם את חלקי הלקוח וגם את חלקי השרת של האפליקציה ל-Cloudflare.

שלבים אפשריים בהמשך כוללים:

הוספת binding לשירות אחר של Cloudflare, כגון מרחב שמות KV או מסד נתונים D1
הרחבת ה-API כך שיכלול נתיבים נוספים
שימוש בספרייה, כגון Hono ↗︎ או tRPC ↗︎, ב-Worker של ה-API

מדריך: SPA של React עם API

#מבוא

#הגדרה וקביעת תצורה של ה-SPA של React

#יצירת שלד לפרויקט Vite

#הוספת התלויות של Cloudflare

#הוספת תוסף Vite של Cloudflare לפרויקט

#יצירת קובץ התצורה של Worker

#עדכון הקובץ .gitignore

#הרצת שרת הפיתוח

#הוספת Worker של API

#הוספת טיפוסי TypeScript של Workers

#הוספת נקודת הכניסה של Worker לתצורה

#הוספת ה-API Worker

#קריאה ל-API מהלקוח

#בניית האפליקציה

#תצוגה מקדימה של האפליקציה

#פריסה ל-Cloudflare

#השלבים הבאים

#עדכון הקובץ `.gitignore`