Edge Computing mit Claude Code: Workers, Cache und regionale Routen

Edge Computing bedeutet, kleine Entscheidungen nahe beim Nutzer zu treffen. Es bedeutet nicht, das gesamte Backend an den Rand des Netzes zu verschieben. Sinnvolle Aufgaben sind regionale Weiterleitungen, kurze Caches, A/B-Zuweisungen oder einfache Zugriffssperren, bevor eine Anfrage die Hauptanwendung erreicht.

Eine Edge Runtime ist trotzdem kein magischer Performance-Schalter. Sie ist kein normaler Node.js-Server. Verfügbare APIs, Laufzeit, Pakete, Request-Metadaten und Cache-Verhalten haben klare Grenzen. Wenn du Claude Code nur bittest, etwas „edge-ready“ zu machen, kann es Node-only APIs importieren, den falschen Cache Key bauen oder Länderinformationen für Entscheidungen nutzen, die eigentlich authentifizierte Serverdaten brauchen.

Dieser Leitfaden basiert auf offizieller Dokumentation, geprüft am 2. Juni 2026. Halte diese Quellen offen: Cloudflare Workers, Workers Request API, Workers Cache API, Vercel Edge Runtime, Deno Deploy runtime und Claude Code overview. Für tiefere Plattformdetails lies auch Cloudflare Workers mit Claude Code und Vercel Edge Functions mit Claude Code.

Erst entscheiden, was an die Edge gehört

Der erste praktische Schritt ist die Trennung zwischen Eingangskontrolle und Geschäftslogik. Wenn eine Entscheidung aus URL, Headern, Cookies oder einem kleinen Body getroffen werden kann, passt sie oft zur Edge. Wenn tiefe Datenbankabfragen, lange LLM-Aufrufe, Bildverarbeitung, PDF-Erstellung, Zahlungsabschluss oder Hintergrundjobs nötig sind, gehört die Arbeit in eine normale API oder Queue.

Anwendungsfall	Warum Edge passt	Besser nicht an der Edge
Land- oder Sprachrouting	Länder- und Sprachheader wählen schnell den Einstieg	Steuern, Rechnungen, Lagerbestand
Kurzer Cache	Öffentliche Antworten werden nah am Nutzer wiederverwendet	DB-Updates und Regeneration
A/B-Zuweisung	Cookie legt Variante vor dem Rendering fest	Statistik und Umsatzentscheidung
Leichte Auth-Sperre	Preview und Admin werden früh blockiert	Session-Erstellung und Rechteprüfung
Webhook-Eingang	Kleine Signaturprüfung weist schlechte Requests ab	Zahlung, E-Mail, Retry

Nimm diese Tabelle in den Prompt für Claude Code auf. Das Ergebnis wird besser prüfbar, weil Edge-Arbeit und Origin-Arbeit schon vor der Codegenerierung getrennt sind.

flowchart LR
  User["User request"] --> Edge["Edge runtime"]
  Edge --> Geo["Country / language branch"]
  Edge --> Cache["Short cache"]
  Edge --> Gate["Light auth gate"]
  Edge --> Origin["Origin API / database"]
  Origin --> Queue["Queue or background work"]

Prompt für Claude Code

Bei Edge-Aufgaben sollte der Prompt Grenzen beschreiben, nicht nur Geschwindigkeit verlangen. Claude Code kann schnell Code erzeugen, aber Cache Keys, regionale Zweige, Secrets und Prüfkommandos fehlen leicht, wenn sie nicht explizit gefordert werden.

Implement a small Cloudflare Workers + TypeScript Edge runtime API.

Files:
- wrangler.toml
- src/index.ts

Requirements:
- GET /health returns JSON
- GET /api/edge-content returns locale and CTA copy based on country
- Use request.cf.country when Cloudflare provides it
- Also support a CF-IPCountry header for local curl verification
- Cache each locale separately for 60 seconds with the Cache API
- Return cache hit/miss through X-Edge-Cache
- Use Web APIs such as Request, Response, URL, and crypto; do not use Node-only APIs
- Include at least three curl or build commands that verify the behavior

Do not:
- Use pseudocode
- Hard-code API tokens or secrets
- Treat country code as proof for billing, permissions, or legal decisions

Erkläre ein paar Begriffe direkt im Auftrag. runtime ist die Umgebung, in der der Code läuft. cache key ist der Name, unter dem eine Antwort im Cache gefunden wird. colo ist die Kennung eines Cloudflare-Rechenzentrums. Diese kurzen Definitionen helfen Claude Code, verständlichere Kommentare und Übergaben zu schreiben.

Kopierbares Beispiel für Cloudflare Workers

Der folgende Worker ist bewusst klein. /api/edge-content liest das Land aus Cloudflare-Metadaten oder aus einem lokalen Testheader, ordnet es einer Locale zu und speichert die Antwort 60 Sekunden über die Cache API. Mit CF-IPCountry kannst du die regionale Verzweigung lokal per curl testen.

name = "claude-edge-router"
main = "src/index.ts"
compatibility_date = "2026-06-02"

[vars]
DEFAULT_LOCALE = "en"

// src/index.ts
export interface Env {
  DEFAULT_LOCALE: string;
}

type Locale = "ja" | "en" | "zh" | "ko" | "es" | "fr" | "de" | "pt" | "hi" | "id";

type CfRequest = Request & {
  cf?: {
    country?: string;
    colo?: string;
    city?: string;
  };
};

const SUPPORTED_LOCALES = new Set<Locale>([
  "ja",
  "en",
  "zh",
  "ko",
  "es",
  "fr",
  "de",
  "pt",
  "hi",
  "id",
]);

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/health") {
      return json({ ok: true, runtime: "cloudflare-workers" });
    }

    if (url.pathname === "/api/edge-content") {
      return handleEdgeContent(request, env, ctx);
    }

    return json({ error: "not_found" }, 404);
  },
} satisfies ExportedHandler<Env>;

async function handleEdgeContent(
  request: Request,
  env: Env,
  ctx: ExecutionContext
): Promise<Response> {
  const url = new URL(request.url);
  const country = getCountry(request);
  const locale = localeFromCountry(country, env.DEFAULT_LOCALE);
  const cacheKey = buildCacheKey(request, locale);
  const cached = await caches.default.match(cacheKey);

  if (cached) {
    return withHeaders(cached, {
      "X-Edge-Cache": "HIT",
      "X-Edge-Locale": locale,
    });
  }

  const body = {
    locale,
    country,
    colo: getColo(request),
    path: url.pathname,
    cta: localizedCta(locale),
    generatedAt: new Date().toISOString(),
  };

  const response = json(body, 200, {
    "Cache-Control": "public, max-age=0, s-maxage=60, stale-while-revalidate=300",
    "X-Edge-Cache": "MISS",
    "X-Edge-Locale": locale,
  });

  ctx.waitUntil(caches.default.put(cacheKey, response.clone()));
  return response;
}

function buildCacheKey(request: Request, locale: Locale): Request {
  const url = new URL(request.url);
  url.search = "";
  url.pathname = `/__edge-cache/${locale}${url.pathname}`;
  return new Request(url.toString(), { method: "GET" });
}

function getCountry(request: Request): string {
  const cf = (request as CfRequest).cf;
  return (
    request.headers.get("CF-IPCountry") ||
    request.headers.get("x-country") ||
    cf?.country ||
    "US"
  ).toUpperCase();
}

function getColo(request: Request): string {
  return (request as CfRequest).cf?.colo || "local";
}

function localeFromCountry(country: string, fallback: string): Locale {
  const normalizedFallback = SUPPORTED_LOCALES.has(fallback as Locale)
    ? (fallback as Locale)
    : "en";

  switch (country) {
    case "JP":
      return "ja";
    case "CN":
    case "TW":
    case "HK":
      return "zh";
    case "KR":
      return "ko";
    case "ES":
    case "MX":
    case "AR":
      return "es";
    case "FR":
      return "fr";
    case "DE":
      return "de";
    case "BR":
    case "PT":
      return "pt";
    case "IN":
      return "hi";
    case "ID":
      return "id";
    default:
      return normalizedFallback;
  }
}

function localizedCta(locale: Locale): string {
  const messages: Record<Locale, string> = {
    ja: "Claude Code教材を見る",
    en: "Explore Claude Code templates",
    zh: "查看 Claude Code 教材",
    ko: "Claude Code 템플릿 보기",
    es: "Ver plantillas de Claude Code",
    fr: "Voir les modèles Claude Code",
    de: "Claude Code Vorlagen ansehen",
    pt: "Ver modelos de Claude Code",
    hi: "Claude Code टेम्पलेट देखें",
    id: "Lihat template Claude Code",
  };
  return messages[locale];
}

function json(data: unknown, status = 200, headers: HeadersInit = {}): Response {
  return new Response(JSON.stringify(data, null, 2), {
    status,
    headers: {
      "Content-Type": "application/json; charset=utf-8",
      "X-Content-Type-Options": "nosniff",
      ...headers,
    },
  });
}

function withHeaders(response: Response, headers: Record<string, string>): Response {
  const next = new Response(response.body, response);
  for (const [key, value] of Object.entries(headers)) {
    next.headers.set(key, value);
  }
  return next;
}

Der entscheidende Punkt ist der Cache Key: Er enthält locale. Ohne das könnte ein japanischer CTA an einen deutschen oder englischen Besucher ausgeliefert werden. Gleichzeitig wird die Query entfernt, damit Parameter wie utm_source den Cache nicht in viele nutzlose Einträge zerlegen.

Muster auf Vercel und Deno übertragen

Vercel Edge Middleware ist nützlich, bevor eine Seite gerendert wird. Sie kann Header setzen, einen A/B-Bucket speichern und regionale Einstiege weiterleiten. Beachte die Edge-Runtime-Grenzen und vermeide Pakete, die Node-only APIs benötigen.

// middleware.ts
import { NextRequest, NextResponse } from "next/server";

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

export function middleware(request: NextRequest) {
  const country = request.headers.get("x-vercel-ip-country") || "US";
  const bucket = request.cookies.get("edge_bucket")?.value || chooseBucket();
  const response = NextResponse.next();

  response.headers.set("x-edge-country", country);
  response.headers.set("x-edge-bucket", bucket);
  response.cookies.set("edge_bucket", bucket, {
    maxAge: 60 * 60 * 24 * 30,
    sameSite: "lax",
    secure: true,
  });

  if (country === "JP" && request.nextUrl.pathname === "/pricing") {
    return NextResponse.redirect(new URL("/jp/pricing", request.url));
  }

  return response;
}

function chooseBucket(): "a" | "b" {
  const bytes = new Uint8Array(1);
  crypto.getRandomValues(bytes);
  return bytes[0] < 128 ? "a" : "b";
}

Bei Deno Deploy bleibt die Form mit Request und Response gleich. Kopiere aber keine Cloudflare-spezifischen Felder wie request.cf. Header und Umgebungsvariablen unterscheiden sich je Anbieter und müssen im Prompt ausdrücklich stehen.

// main.ts
Deno.serve((request: Request) => {
  const url = new URL(request.url);
  const country = request.headers.get("x-country") || "US";

  if (url.pathname !== "/api/edge-content") {
    return Response.json({ error: "not_found" }, { status: 404 });
  }

  return Response.json({
    runtime: "deno-deploy",
    country,
    message: country === "JP" ? "Japan entry" : "Default edge entry",
  });
});

Prüfkommandos

Edge-Code sollte auf Typen, lokales HTTP-Verhalten, regionale Verzweigung, Cache-Header und Deploy-Bereitschaft geprüft werden. Bitte Claude Code, diese Nachweise in der Übergabe zu hinterlassen.

npm create cloudflare@latest claude-edge-router -- --type=hello-world
cd claude-edge-router
npm install -D typescript wrangler
npx wrangler types
npx tsc --noEmit
npx wrangler dev

In einem zweiten Terminal laufen die curl-Prüfungen.

curl -i http://127.0.0.1:8787/health
curl -i -H "CF-IPCountry: JP" http://127.0.0.1:8787/api/edge-content
curl -i -H "CF-IPCountry: US" http://127.0.0.1:8787/api/edge-content
curl -i -H "CF-IPCountry: JP" "http://127.0.0.1:8787/api/edge-content?utm_source=test"
npx wrangler deploy --dry-run

Das erwartete Verhalten ist klar: Die erste Anfrage für Locale und Pfad liefert X-Edge-Cache: MISS, die nächste HIT. JP wird zu ja, US zu en, und der Tracking-Parameter erzeugt keinen separaten Cache-Eintrag.

Häufige Fehler

Der erste Fehler ist, zu viel an die Edge zu verschieben. Lange LLM-Aufrufe, schwere ORM-Arbeit, PDFs, Bildverarbeitung und komplexe Abrechnung gehören meist in eine Origin-API oder Queue. Edge ist ein Eingangstor, nicht das gesamte Backend.

Der zweite Fehler ist ein zu grober oder zu feiner Cache Key. Wenn Locale, Login-Zustand, Preis oder Experiment-Bucket die Antwort verändern, müssen sie Teil des Keys sein. Wenn Störfelder wie utm_* oder Timestamps enthalten sind, trifft der Cache kaum noch.

Der dritte Fehler ist zu viel Vertrauen in Geografie. request.cf.country und x-vercel-ip-country sind gut für Standarderlebnisse, aber kein Beweis für Steuern, Alter, Rechte oder Abrechnung. VPN, Firmenproxy und CDN-Routing können das Land verändern.

Der vierte Fehler ist ein zu vager Auftrag an Claude Code. „Baue es mit Workers“ sagt nicht, ob Cache API, KV, D1, Vercel-Kompatibilität oder Origin-Fallback gewünscht ist. Vergleiche die Grenze mit Claude Code serverless functions und Claude Code Performance-Optimierung.

Umsatzpfad und nächste Schritte

Auf einer mehrsprachigen Content-Seite kann Edge Runtime auch den Umsatzpfad verbessern. Du kannst den Text für ein kostenloses PDF lokalisieren, Nutzer zur passenden Sprache schicken, Werbeparameter vor dem Cache normalisieren und Template-CTAs schnell ausliefern.

Für wiederverwendbare Materialien schau dir die ClaudeCodeLab Produkte an. Wenn dein Team Prompts, Review-Regeln und die Grenze zwischen Edge und Node standardisieren möchte, passt Claude Code Training und Beratung. Für einen schnellen Einstieg nutze den kostenlosen Spickzettel.

Tatsächlich getestetes Ergebnis

Für dieses Update hat Masa den lokalen Workers-Entwurf mit CF-IPCountry: JP und CF-IPCountry: US getestet und locale, X-Edge-Cache sowie den Cache Key ohne Tracking-Parameter geprüft. Nützlich war die Erkenntnis, dass lokale Testheader vor request.cf.country gelesen werden sollten; sonst kann die Länder-Verzweigung bei wiederholten Checks fest wirken. Der Cache Key nutzt außerdem /__edge-cache/${locale}${pathname}, damit regionale Inhalte nicht vermischt werden. Im Auftrag an Claude Code sollte deshalb stehen, dass Header-Priorität, regionale Verzweigung und Cache Key gemeinsam geprüft werden.

Zusammenfassung

Edge Computing bedeutet nicht, alles an die Edge zu verschieben. Es bedeutet, kleine Request-Entscheidungen nahe beim Nutzer zu treffen und schwere Arbeit sowie endgültige Entscheidungen in der normalen API zu lassen. Gib Claude Code Laufzeitgrenzen, Cache-Key-Regeln, regionale Zweige und Prüfkommandos von Anfang an. Das Ergebnis ist schneller und deutlich leichter zu prüfen.