Edge computing avec Claude Code : Workers, cache et routage régional

L’edge computing consiste à prendre de petites décisions près de l’utilisateur. Il ne s’agit pas de déplacer tout le backend vers le bord du réseau. Il s’agit plutôt de gérer une redirection, un cache court, une attribution A/B ou un blocage évident avant que la requête atteigne l’application principale.

Un Edge runtime n’est donc pas un bouton magique de performance. Ce n’est pas un serveur Node.js classique. Les APIs disponibles, le temps d’exécution, les dépendances, les métadonnées de requête et le comportement du cache ont des limites. Si vous demandez seulement à Claude Code de « rendre l’application edge-ready », il peut importer des APIs réservées à Node, oublier la langue dans la clé de cache ou utiliser le pays comme preuve pour la facturation et les permissions.

Ce guide s’appuie sur la documentation officielle vérifiée le 2 juin 2026. Gardez ces liens ouverts : Cloudflare Workers, Workers Request API, Workers Cache API, Vercel Edge Runtime, Deno Deploy runtime et Claude Code overview. Pour approfondir chaque plateforme, lisez aussi Cloudflare Workers avec Claude Code et Vercel Edge Functions avec Claude Code.

Décider ce qui appartient à l’Edge

La première étape consiste à séparer la décision d’entrée de la logique métier. Si la décision peut être prise avec l’URL, les en-têtes, les cookies ou un petit corps de requête, elle peut convenir à l’Edge. Si elle demande de grosses lectures en base, de longs appels LLM, du traitement d’image, de la génération PDF, une validation de paiement ou un traitement asynchrone, laissez-la dans une API classique ou une file.

Cas d’usage	Pourquoi l’Edge convient	À garder ailleurs
Routage par pays ou langue	Un code pays ou un en-tête de langue choisit vite l’entrée	Taxes, factures, stock
Cache court	Une réponse publique peut être servie près de l’utilisateur	Mises à jour DB et régénération
Attribution A/B	Un cookie choisit la variante avant le rendu	Analyse statistique et décision business
Authentification légère	Preview et admin peuvent être bloqués tôt	Création de session et audit des permissions
Entrée de webhook	Une petite signature rejette les mauvaises requêtes	Paiement, e-mail, retry

Placez ce tableau dans le prompt donné à Claude Code. La sortie sera plus facile à relire, car le travail de l’Edge et celui de l’origine sont séparés avant la génération de code.

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 à donner à Claude Code

Pour un développement Edge, le prompt doit décrire les contraintes, pas seulement demander de la vitesse. Claude Code peut produire vite, mais les clés de cache, les branches régionales, les secrets et les commandes de vérification sont souvent oubliés s’ils ne sont pas demandés.

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

Définissez aussi quelques termes. runtime signifie l’environnement d’exécution. cache key désigne le nom utilisé pour retrouver une réponse en cache. colo est l’identifiant d’un centre de données Cloudflare. Ces explications aident Claude Code à produire des commentaires et une note de livraison compréhensibles.

Exemple Cloudflare Workers copiable

Le Worker suivant reste volontairement petit. /api/edge-content lit le pays depuis les métadonnées Cloudflare ou depuis un en-tête local de test, le convertit en locale et conserve la réponse 60 secondes avec Cache API. L’en-tête CF-IPCountry permet de tester la branche avec curl avant le déploiement.

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;
}

Le détail essentiel est la clé de cache : elle contient locale. Sinon une CTA japonaise pourrait être servie à un visiteur francophone. La query est aussi supprimée afin que des paramètres comme utm_source ne créent pas des centaines d’entrées inutiles.

Étendre le modèle à Vercel et Deno

Vercel Edge Middleware est utile avant le rendu d’une page. Il peut ajouter des en-têtes, conserver un bucket A/B et rediriger une entrée régionale. Respectez les limites de l’Edge Runtime et évitez les packages qui ont besoin d’APIs Node-only.

// 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";
}

Avec Deno Deploy, gardez la même forme basée sur Request et Response, mais ne copiez pas les champs propres à Cloudflare comme request.cf. Les en-têtes et variables d’environnement changent selon le fournisseur.

// 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",
  });
});

Commandes de vérification

Un code Edge doit être vérifié sur les types, le HTTP local, la branche régionale, les en-têtes de cache et la préparation au déploiement. Demandez à Claude Code de laisser ces preuves dans sa livraison.

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

Dans un autre terminal, lancez curl.

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

Le résultat attendu est simple : la première requête pour une locale et un chemin renvoie X-Edge-Cache: MISS, la suivante renvoie HIT. JP devient ja, US devient en, et le paramètre de tracking ne crée pas une entrée de cache séparée.

Pièges fréquents

Le premier piège consiste à mettre trop de travail dans l’Edge. Les longs appels LLM, les ORM lourds, les PDFs, les images et la facturation complexe doivent rester dans une API d’origine ou une file de fond. L’Edge est une porte d’entrée, pas tout le backend.

Le deuxième piège est une mauvaise clé de cache. Si la locale, la session, le prix ou le bucket expérimental change la réponse, il doit être dans la clé. Si vous ajoutez du bruit comme utm_* ou des timestamps, la cache touchera rarement.

Le troisième piège est de trop croire la géographie. request.cf.country et x-vercel-ip-country sont utiles pour des valeurs par défaut d’expérience, mais ne prouvent ni taxe, ni âge, ni permission, ni facturation. VPN, proxy d’entreprise et routage CDN peuvent modifier le pays observé.

Le quatrième piège est de donner seulement un nom de plateforme à Claude Code. « Fais-le avec Workers » ne dit pas s’il faut Cache API, KV, D1, compatibilité Vercel ou fallback vers l’origine. Pour choisir la frontière, comparez avec fonctions serverless avec Claude Code et optimisation de performance.

Parcours revenu et suite

Sur un site de contenu multilingue, Edge runtime peut aussi améliorer le parcours de revenu. Vous pouvez adapter le texte du PDF gratuit, diriger le lecteur vers la bonne langue, normaliser les paramètres publicitaires avant le cache et garder les CTA de modèles rapides.

Pour des ressources réutilisables, consultez les produits ClaudeCodeLab. Pour une équipe qui veut standardiser les prompts, les règles de revue et la limite entre Edge et Node, voyez la formation et consultation Claude Code. Pour commencer par un flux court, utilisez la fiche gratuite.

Résultat du test réel

Pour cette mise à jour, Masa a testé le Worker local en alternant CF-IPCountry: JP et CF-IPCountry: US, puis a vérifié locale, X-Edge-Cache et la clé de cache sans paramètres de tracking. Le point utile est qu’en local il vaut mieux lire les en-têtes de test avant request.cf.country; sinon la branche pays peut paraître bloquée lors de vérifications répétées. La clé utilise aussi /__edge-cache/${locale}${pathname} pour éviter de mélanger les contenus régionaux. Dans le brief donné à Claude Code, demandez de relire ensemble la priorité des en-têtes, la branche géographique et la clé de cache.

Résumé

L’edge computing ne consiste pas à tout déplacer à l’Edge. Il consiste à placer près de l’utilisateur les petites décisions de requête, tout en gardant le travail lourd et les décisions finales dans l’API normale. Donnez à Claude Code les limites du runtime, les règles de cache key, les branches régionales et les commandes de vérification dès le départ. Le résultat sera plus rapide et surtout plus facile à relire.