rodolfo.gg
Go back

Wie man eine Svelte+SvelteKit-Anwendung auf Cloudflare Workers (free) deployt.

CC BY-NC-ND 4.0
Rodolfo González González
de en es fr
Wie man eine Svelte+SvelteKit-Anwendung auf Cloudflare Workers (free) deployt.

Einführung

Laut Wikipedia:

Cloudflare, Inc. ist ein amerikanisches Unternehmen, das ein Content Delivery Network, Internet-Sicherheitsdienste und verteilte Domain-Name-Server-Dienste bereitstellt, die zwischen dem Besucher und dem Hosting-Anbieter des Cloudflare-Nutzers stehen und als Reverse Proxy für Websites fungieren.

Workers basiert auf einer leichtgewichtigen Ausführungsumgebung auf Basis von Node.js (nicht Node.js direkt). Es ist viel schneller und praktischer als die Verwendung eines FaaS auf Aliyun FC oder Amazon Lambda für das Deployen von Anwendungen wie diesem mit Astro erstellten Blog, obwohl jede Technologie ihre eigenen Vor- und Nachteile hat. Ein Vorteil von Workers ist die Ausführungsgeschwindigkeit. Ein weiterer ist der Preis.

Diese Anleitung zeigt, wie man eine Svelte+SvelteKit-Anwendung auf Cloudflare Workers (free) deployt.

1) Was in Cloudflare (Dashboard) zu tun ist

  1. Ein Cloudflare-Konto erstellen/verwenden (Free-Plan).
  2. Zu Entwicklung -> Workers und Pages gehen und Workers im Konto aktivieren.
  3. (Empfohlen) Ein API Token für das Deployen von der CLI erstellen:
  4. Zu Konto verwalten -> Konto-API-Token gehen.
  5. Unter Account Resources: das eigene Konto auswählen.
  6. Token erstellen
  7. Die Vorlage Edit Cloudflare Workers verwenden (sie hat die minimal erforderlichen Berechtigungen)
  8. Bei Verwendung einer eigenen Domain:
  1. Die Zone-Ressourcen entsprechend den Zonen auswählen, die der Token abdecken soll.
  2. Auf Continue to summary → Create Token klicken.

  1. Bei Verwendung einer eigenen Domain:

    • Die Zone (ihredomain.com) in Cloudflare haben.
    • Beim deployteten Worker: Settings -> Domains & Routes -> Add Custom Domain

  2. Der neue Token kann getestet werden:

Terminal window
curl "https://api.cloudflare.com/client/v4/accounts/xxx123/tokens/verify" \
-H "Authorization: Bearer cfat_ABCD_my_token"

2) Was im Projekt zu konfigurieren ist

Das Projekt muss auf einen reinen Worker ausgerichtet sein:

wrangler.toml
  - `main = "build/_worker.js"`
  - `[assets] directory = "build", binding = "ASSETS"`

Falls die account_id fehlt, hinzufügen:

wrangler.toml
account_id = "ihre_account_id"

Die account_id findet man im Cloudflare-Dashboard, in der rechten Seitenleiste der Domain, oder mit:

bunx wrangler whoami

Es ist natürlich sehr wichtig, den adapter-cloudflare zu verwenden:

svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';

Lokale Anforderungen

  1. Abhängigkeiten:
  1. Token in der lokalen Umgebung konfigurieren
Terminal window
export CLOUDFLARE_API_TOKEN=cfat_ABCD_my_token

Oder dauerhaft in ~/.bashrc, ~/.zshrc oder der entsprechenden Datei für die Shell:

Terminal window
echo 'export CLOUDFLARE_API_TOKEN=ihr_token_hier' >> ~/.bashrc

Alternativ mit wrangler:

Terminal window
bunx wrangler login

Dies öffnet einen Browser für OAuth. Persönlich mag ich das nicht.

Bei Präferenz für direkten Token:

Terminal window
bunx wrangler config

3) Variablen und Geheimnisse (wichtig)

In der aktuellen App

Bei Verwendung von import.meta.env.VITE_* (Build-Zeit) bedeutet das:

Kritische Beispiele könnten sein:

Laufzeit-Geheimnisse (optional)

Wenn Sie später Geheimnisse zur Laufzeit hinzufügen möchten:

Terminal window
bunx wrangler secret put VARIABLENNAME

und sie von env.VARIABLENNAME lesen.

4) Build + Deploy (Schritt für Schritt)

In den folgenden Schritten kann npm durch bun in den Befehlen ersetzt werden:

  1. Abhängigkeiten installieren:
Terminal window
npm ci
  1. Token konfigurieren:
Terminal window
export CLOUDFLARE_API_TOKEN=ihr_token

  1. Build-.env vorbereiten (mit den korrekten VITE_*-Werten).

  2. Build:

Terminal window
make build
# npm run build
# bun run build
  1. Ausgabe überprüfen:
  1. Worker lokal testen:
Terminal window
make preview
# bunx wrangler dev
  1. Deployen:
Terminal window
make deploy
# bunx wrangler deploy
  1. Den Worker testen, der verfügbar sein wird unter:

https://example-frontend.ihre-subdomain.workers.dev

oder unter Ihrer benutzerdefinierten Domain, wenn Sie diese im Dashboard konfigurieren.

5) OIDC-Konfiguration (Zitadel oder ein anderer Anbieter) für die Produktion

Bei Verwendung eines OIDC-Anbieters wie Zitadel müssen die erforderlichen Endpunkte beim Anbieter registriert werden:

  1. Redirect URI(s) (Login-Callback).
  2. Post-logout redirect URI(s).
  3. Web origins des Frontends.

6) Post-Deploy-Überprüfungen

Zum Anzeigen von Logs:

Terminal window
npx wrangler tail

7) Free-Workers-Limits, die zu beachten sind (überprüft am 7. April 2026)

Bei Überschreitung dieser Limits werden 1027/Quota-Fehler auftreten.

8) Typische Fehler

  1. Cannot read properties of undefined (reading 'fetch')
  1. Leere VITE_*-Variablen in der Produktion
  1. Zitadel-Login schlägt in der Produktion fehl

9) Deploy auf eigener Domain

Es gibt 2 Möglichkeiten, dies zu tun, vorausgesetzt die Domain befindet sich in Cloudflare:

A. Mit wrangler.toml

Routen konfigurieren:

routes = [
  { pattern = "www.example.com/*", zone_name = "example.com" }
]

Dann normales Deployen:

Terminal window
bunx wrangler deploy

B. Im Cloudflare-Dashboard

  1. Zu Workers & Pages → Ihr Worker → Settings → Triggers gehen
  2. Auf Add Custom Domain klicken
  3. www.example.com eingeben
  4. Cloudflare erstellt automatisch den DNS-Eintrag und das TLS-Zertifikat

Domain außerhalb von Cloudflare

Falls die Domain nicht in Cloudflare ist:

Zunächst muss die Domain zu Cloudflare hinzugefügt werden (oder zumindest ein externer DNS-Eintrag verwendet werden):

Im DNS des Registrars einen CNAME-Eintrag erstellen:

In tinydns zum Beispiel:

Terminal window
Cwww:ihr-projekt.ihre-subdomain.workers.dev:86400

Dann in Cloudflare zum Worker gehen und unter Triggers auf Add Custom Domain klicken und www.example.com hinzufügen.

Unterschied zwischen routes und custom_domain

Merkmalroutescustom_domain
Zone in CF erforderlichJaJa
In toml konfigurierbarJaJa
Automatisches TLSManuell (bereits vorhanden)Automatisch
Mit anderen Workers geteiltJa (nach Muster)Nein

Für eine dem Worker gewidmete Subdomain ist custom_domain die sauberste Option:

wrangler.toml
routes = [
  { pattern = "ssr.example.com/*", custom_domain = true, zone_name = "example.com" }
]

Oder die alternative Syntax:

[[env.production.routes]]
pattern = "ssr.example.com/*"
zone_name = "example.com"

Bonus: Nützliche Makefile-Regeln

deploy:
  bunx wrangler deploy


preview:
  bunx wrangler dev


build:
  @echo "Building with $(DOTENV_FILE)"
  DOTENV_FILE=$(DOTENV_FILE) bun run build

Verwendete offizielle Quellen

Share this post on:
Share this post via WhatsApp Share this post on Facebook Share this post on X Share this post via Telegram Share this post on Pinterest Share this post via email
Previous Post
Wie man Autorisierungstoken auf HuggingFace erhält.
Next Post
Jean-Michel Jarre: Rendez-vous Houston, eine Stadt im Konzert.