Edge Computing con Claude Code: Workers, caché y rutas por región

El edge computing consiste en tomar decisiones pequeñas cerca del usuario. No significa mover todo el backend al borde de la red. Significa decidir redirecciones, devolver contenido público en caché, asignar una variante A/B o bloquear una solicitud claramente inválida antes de que llegue a la aplicación principal.

Por eso no conviene tratar el Edge runtime como un botón mágico de rendimiento. No es un servidor Node.js normal. Tiene límites en APIs disponibles, tiempo de ejecución, paquetes, metadatos de la solicitud y comportamiento de caché. Si le pides a Claude Code solo “hazlo compatible con edge”, puede importar APIs exclusivas de Node, construir una clave de caché demasiado amplia o usar el país como si fuera una prueba para facturación y permisos.

Esta guía parte de documentación oficial revisada el 2 de junio de 2026. Mantén a mano Cloudflare Workers, Workers Request API, Workers Cache API, Vercel Edge Runtime, Deno Deploy runtime y Claude Code overview. Para profundizar por plataforma, revisa también Cloudflare Workers con Claude Code y Vercel Edge Functions con Claude Code.

Decide qué va al Edge

La primera decisión práctica es separar el “control de entrada” de la lógica de negocio. Si la decisión se puede tomar con la URL, cabeceras, cookies o un cuerpo de solicitud pequeño, puede ser una buena candidata para Edge. Si requiere lecturas profundas de base de datos, llamadas largas a un LLM, procesamiento de imágenes, PDF, cierre de pagos o trabajos de fondo, déjalo en una API normal o en una cola.

Caso de uso	Por qué encaja en Edge	Déjalo fuera del Edge
Ruta por país o idioma	Un código de país o cabecera de idioma decide la entrada rápido	Impuestos, facturas, inventario
Caché breve	Una respuesta pública se sirve cerca del usuario	Actualizaciones de DB y regeneración
Asignación A/B	Una cookie decide la variante antes de renderizar	Análisis estadístico y decisión de ingresos
Puerta de autenticación ligera	Preview y admin se bloquean temprano	Creación de sesión y auditoría de permisos
Entrada de webhook	Una firma pequeña puede rechazar solicitudes malas	Pagos, correos y reintentos

Incluye esta tabla en el prompt para Claude Code. La respuesta será más fácil de revisar porque el trabajo del Edge y el trabajo del origen quedan separados desde el principio.

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 para Claude Code

En trabajos de Edge, el prompt debe describir restricciones, no solo velocidad. Claude Code puede generar código rápido, pero las claves de caché, la rama regional, los secretos y los comandos de verificación se olvidan si no aparecen como requisitos.

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

Conviene explicar tres términos. runtime es el entorno donde corre el código. cache key es el nombre usado para encontrar una respuesta en caché. colo es el identificador del centro de datos de Cloudflare. Estas definiciones ayudan a que Claude Code escriba comentarios y notas de entrega más útiles para principiantes.

Ejemplo copiable de Cloudflare Workers

El siguiente Worker es pequeño a propósito. /api/edge-content lee el país desde metadatos de Cloudflare o desde una cabecera local de prueba, lo convierte en un locale y guarda la respuesta durante 60 segundos con Cache API. La cabecera CF-IPCountry permite probar la ruta con curl antes de desplegar.

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

El detalle crítico es la clave de caché: contiene locale. Sin eso, una CTA japonesa podría devolverse a un visitante en español o inglés. También eliminamos la query para que parámetros como utm_source no rompan la caché en cientos de entradas inútiles.

Extender el patrón a Vercel y Deno

Vercel Edge Middleware sirve para preparar la solicitud antes del renderizado. Puede añadir cabeceras, persistir un bucket A/B y redirigir una ruta regional. Respeta las restricciones de Edge Runtime y evita paquetes que dependan de APIs exclusivas de Node.

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

En Deno Deploy, conserva la misma forma basada en Web APIs y no copies campos exclusivos de Cloudflare como request.cf. Las cabeceras y variables de entorno cambian por proveedor, así que deben estar explícitas en el prompt.

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

Comandos de verificación

El código Edge debe verificarse en tipos, HTTP local, rama regional, cabeceras de caché y preparación de despliegue. Pide a Claude Code que deje esta evidencia en la entrega.

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

En otra terminal, ejecuta 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

La lectura esperada es simple: la primera solicitud para un locale y ruta devuelve X-Edge-Cache: MISS; la siguiente devuelve HIT. JP se convierte en ja, US en en, y la query de tracking no crea una entrada de caché separada.

Errores frecuentes

El primer error es poner demasiado en Edge. Llamadas largas a LLMs, ORMs pesados, PDF, conversión de imágenes y facturación compleja suelen pertenecer a una API de origen o a una cola. Edge debe ser una puerta de entrada, no todo el backend.

El segundo error es una clave de caché mal diseñada. Si locale, sesión, precio o bucket experimental cambian la respuesta, deben formar parte de la clave. Si metes ruido como utm_* o marcas de tiempo, la caché casi nunca acertará.

El tercer error es confiar demasiado en la geografía. request.cf.country y x-vercel-ip-country sirven para valores por defecto de experiencia, pero no prueban impuestos, edad, permisos ni facturación. VPNs, proxies corporativos y rutas CDN pueden cambiar el país observado.

El cuarto error es dar a Claude Code solo el nombre del proveedor. “Hazlo con Workers” no dice si quieres Cache API, KV, D1, compatibilidad con Vercel o fallback al origen. Para decidir la frontera, compara con funciones serverless con Claude Code y optimización de rendimiento.

Ruta de ingresos y siguiente paso

En un sitio de contenido multilingüe, Edge runtime también ayuda a la ruta de ingresos. Puedes mostrar el texto correcto para un PDF gratuito, enviar al usuario al idioma más cercano, normalizar parámetros de anuncios antes de cachear y mantener rápidas las CTA de plantillas.

Para materiales reutilizables, revisa productos de ClaudeCodeLab. Para equipos que quieran prompts, reglas de revisión y límites entre Edge y Node, revisa formación y consultoría de Claude Code. Si quieres un flujo rápido primero, empieza por la chuleta gratuita.

Resultado de la prueba real

Para esta actualización, Masa probó el Worker local alternando CF-IPCountry: JP y CF-IPCountry: US, revisando locale, X-Edge-Cache y la clave de caché sin parámetros de tracking. El hallazgo útil fue que, en local, conviene leer primero las cabeceras de prueba y luego caer a request.cf.country; si no, la rama de país puede parecer fija en comprobaciones repetidas. La clave también usa /__edge-cache/${locale}${pathname} para no mezclar contenido regional. Cuando pidas esto a Claude Code, solicita revisar prioridad de cabeceras, rama geográfica y cache key juntas.

Resumen

Edge computing no es mover todo al borde. Es colocar decisiones pequeñas cerca del usuario y mantener el trabajo pesado y las decisiones finales en la API normal. Da a Claude Code límites del runtime, reglas de cache key, ramas regionales y comandos de verificación desde el inicio. El resultado será más rápido y mucho más fácil de revisar.