Cloudflare Workers + Vite

Mit Cloudflare Workers, Vite und dem @cloudflare/vite-plugin kannst du eine Fullstack-Anwendung erstellen. Diese Konfiguration bietet einen schnellen Vite-Entwicklungsserver, serverseitiges Rendering mit Honos JSX-Renderer und von Vite gebündelte clientseitige Skripte. Alles läuft auf Cloudflare Workers.

Dies ist die empfohlene Vorgehensweise, um ein neues Fullstack-Projekt auf Cloudflare zu starten.

1. Einrichtung

Für Cloudflare Workers mit Vite steht eine Projektvorlage zur Verfügung. Starte dein Projekt mit dem Befehl „create-hono“. Wähle für dieses Beispiel die Vorlage cloudflare-workers+vite aus.

npm

npm create hono@latest my-app

yarn

yarn create hono my-app

pnpm

pnpm create hono my-app

bun

bun create hono@latest my-app

deno

deno init --npm hono my-app

Wechsle nach my-app und installiere die Abhängigkeiten.

npm

cd my-app
npm i

yarn

cd my-app
yarn

pnpm

cd my-app
pnpm i

bun

cd my-app
bun i

Unten findest du eine grundlegende Verzeichnisstruktur.

./
├── 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

Die Datei vite.config.ts kombiniert das Cloudflare-Plugin mit vite-ssr-components für 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. Hello World

Bearbeite src/index.tsx wie folgt:

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

Der renderer wird in src/renderer.tsx definiert. Er verwendet Honos JSX-Renderer-Middleware zusammen mit vite-ssr-components, das den Vite-Client und die Assets einbindet:

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

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

3. Ausführen

Starte den Entwicklungsserver lokal. Öffne anschließend http://localhost:5173 in deinem Webbrowser.

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

4. Bereitstellung

Wenn du ein Cloudflare-Konto hast, kannst du die Anwendung auf Cloudflare bereitstellen. Das Skript deploy baut sie mit Vite und veröffentlicht sie anschließend mit Wrangler.

npm

npm run deploy

yarn

yarn deploy

pnpm

pnpm run deploy

bun

bun run deploy

Bindings

Du kannst Cloudflare-Bindings wie Variablen, KV, D1 und weitere verwenden. Konfiguriere die Bindings in wrangler.jsonc. Um beispielsweise eine Variable namens MY_NAME hinzuzufügen:

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

Um die Typen für deine Bindings zu generieren, führe das Skript cf-typegen aus:

npm

npm run cf-typegen

yarn

yarn cf-typegen

pnpm

pnpm run cf-typegen

bun

bun run cf-typegen

Dadurch wird eine Schnittstelle CloudflareBindings generiert. Übergib sie als generischen Typparameter an Hono:

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

Greife anschließend über c.env auf die Bindings zu:

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

Clientseite

Mit vite-ssr-components kannst du clientseitige Skripte über Vite laden. Füge eine Script-Komponente hinzu, die auf den Einstiegspunkt deines Clients verweist. Vite übernimmt das Bündeln sowohl für die Entwicklung als auch für die Produktion:

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

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

Weitere Informationen findest du in der Dokumentation zu @cloudflare/vite-plugin und bei vite-ssr-components.