Cloudflare Workers + Vite

يمكنك بناء تطبيق متكامل (full-stack) على Cloudflare Workers مع Vite باستخدام @cloudflare/vite-plugin. يمنحك هذا الإعداد خادم تطوير Vite سريعًا، وتصييرًا من جانب الخادم (SSR) باستخدام مُصيِّر JSX الخاص بـ Hono، ونصوصًا من جانب العميل تُدمج بواسطة Vite — كل ذلك يعمل على Cloudflare Workers.

هذه هي الطريقة الموصى بها لبدء مشروع كامل المكدس (full-stack) جديد على Cloudflare.

1. الإعداد

يتوفّر قالب بدء (starter) لـ Cloudflare Workers مع Vite. ابدأ مشروعك باستخدام الأمر "create-hono". اختر cloudflare-workers+vite قالب لهذا المثال.

npm create hono@latest my-app

yarn create hono my-app

pnpm create hono my-app

bun create hono@latest my-app

deno init --npm hono my-app

انتقل إلى my-app وثبّت التبعيات.

cd my-app
npm i

cd my-app
yarn

cd my-app
pnpm i

cd my-app
bun i

فيما يلي بنية دليل أساسية.

./
├── package.json
├── public // Put your static files here.
├── src
│   ├── index.tsx // The entry point for server-side.
│   ├── renderer.tsx
│   └── style.css
├── tsconfig.json
├── vite.config.ts
└── wrangler.jsonc

الـ vite.config.ts يجمع إضافة Cloudflare مع vite-ssr-components من أجل SSR:

import { cloudflare } from '@cloudflare/vite-plugin'
import { defineConfig } from 'vite'
import ssrPlugin from 'vite-ssr-components/plugin'

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

2. مرحبًا بالعالم

تعديل src/index.tsx مثل ما يلي:

import { Hono } from 'hono'
import { renderer } from './renderer'

const app = new Hono()

app.use(renderer)

app.get('/', (c) => {
  return c.render(<h1>Hello, Cloudflare Workers!</h1>)
})

export default app

الـ renderer معرّف في src/renderer.tsx باستخدام Hono البرمجية الوسيطة JSX renderer مع vite-ssr-components، الذي يربط عميل Vite وأصوله:

import { jsxRenderer } from 'hono/jsx-renderer'
import { Link, ViteClient } from 'vite-ssr-components/hono'

export const renderer = jsxRenderer(({ children }) => {
  return (
    
      <head>
        <ViteClient />
        <Link href='/src/style.css' rel='stylesheet' />
      </head>
      <body>{children}</body>
    
  )
})

3. تشغيل

شغّل خادم التطوير محليًا. ثم، ادخل إلى http://localhost:5173 في متصفح الويب الخاص بك.

npm run dev

yarn dev

pnpm dev

bun run dev

4. النشر

إذا كان لديك حساب Cloudflare، يمكنك النشر على Cloudflare. حيث deploy يقوم السكربت بالبناء باستخدام Vite ثم النشر باستخدام Wrangler.

npm run deploy

yarn deploy

pnpm run deploy

bun run deploy

الارتباطات

يمكنك استخدام روابط (Bindings) Cloudflare مثل المتغيرات (Variables) و KV و D1 وغيرها. قم بتكوينها في wrangler.jsonc. على سبيل المثال، لإضافة Variable باسم MY_NAME:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-app",
  "compatibility_date": "2025-08-03",
  "main": "./src/index.tsx",
  "vars": {
    "MY_NAME": "Hono",
  },
}

لتوليد الأنواع لارتباطاتك (Bindings)، شغّل cf-typegen script:

npm run cf-typegen

yarn cf-typegen

pnpm run cf-typegen

bun run cf-typegen

يولِّد هذا CloudflareBindings الواجهة. مرّرها إلى Hono كأنواع عامة:

const app = new Hono<{ Bindings: CloudflareBindings }>()

ثم وصل إلى Bindings عبر c.env:

app.get('/', (c) => {
  return c.render(<h1>Hello! {c.env.MY_NAME}</h1>)
})

من جهة العميل

vite-ssr-components يتيح لك تحميل سكربتات جانب العميل عبر Vite. أضف Script مكوّن يشير إلى نقطة دخول عميلك، وتتولى Vite عملية التجميع (bundling) لكل من بيئتي التطوير والإنتاج:

import { jsxRenderer } from 'hono/jsx-renderer'
import { Script, ViteClient } from 'vite-ssr-components/hono'

export const renderer = jsxRenderer(({ children }) => {
  return (
    
      <head>
        <ViteClient />
        <Script src='/src/client.ts' />
      </head>
      <body>{children}</body>
    
  )
})

لمزيد من التفاصيل، راجع @cloudflare/vite-plugin التوثيق و vite-ssr-components.