Edge Computing dengan Claude Code: Workers, cache, dan rute wilayah

Edge computing berarti mengambil keputusan kecil di lokasi yang dekat dengan pengguna. Ini bukan berarti memindahkan seluruh backend ke edge. Contoh yang cocok adalah redirect berdasarkan negara, cache singkat, pembagian A/B test, atau gerbang autentikasi ringan sebelum request masuk ke aplikasi utama.

Edge runtime juga bukan tombol ajaib untuk membuat semua hal lebih cepat. Ia berbeda dari server Node.js biasa. API yang tersedia, durasi eksekusi, paket, metadata request, dan perilaku cache punya batas. Jika kamu hanya meminta Claude Code “jadikan ini edge-ready”, hasilnya bisa mencampur API khusus Node, membuat cache key yang salah, atau memakai country code sebagai bukti untuk billing dan permission.

Panduan ini memakai dokumentasi resmi yang dicek pada 2 Juni 2026. Buka juga Cloudflare Workers, Workers Request API, Workers Cache API, Vercel Edge Runtime, Deno Deploy runtime, dan Claude Code overview. Untuk pendalaman per platform, baca Cloudflare Workers dengan Claude Code dan Vercel Edge Functions dengan Claude Code.

Tentukan apa yang pantas berjalan di Edge

Langkah pertama adalah memisahkan keputusan masuk dari logika bisnis utama. Jika keputusan bisa dibuat dari URL, header, cookie, atau body request kecil, ia mungkin cocok untuk Edge. Jika butuh query database dalam, panggilan LLM panjang, pemrosesan gambar, PDF, penyelesaian pembayaran, atau job background, simpan di API biasa atau queue.

Kasus penggunaan	Mengapa cocok untuk Edge	Simpan di tempat lain
Routing negara atau bahasa	Country code atau language header bisa memilih pintu masuk cepat	Pajak, invoice, stok
Cache singkat	Respons publik bisa dilayani dekat pengguna	Update DB dan regenerasi
Pembagian A/B	Cookie bisa memilih bucket sebelum render	Analisis statistik dan keputusan revenue
Auth gate ringan	Preview dan admin bisa diblokir lebih awal	Pembuatan sesi dan audit izin
Pemeriksaan webhook	Signature kecil bisa menolak request buruk	Pembayaran, email, retry

Masukkan tabel ini ke prompt untuk Claude Code. Kode yang dihasilkan akan lebih mudah direview karena pekerjaan Edge dan pekerjaan origin sudah dipisahkan sejak awal.

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

Untuk implementasi Edge, prompt harus menjelaskan batasan, bukan hanya meminta kecepatan. Claude Code bisa menulis kode cepat, tetapi cache key, cabang wilayah, secret, dan perintah verifikasi mudah terlewat jika tidak ditulis sebagai syarat.

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

Jelaskan istilah penting sejak awal. runtime adalah lingkungan tempat kode berjalan. cache key adalah nama untuk menemukan respons di cache. colo adalah identitas data center Cloudflare. Penjelasan singkat seperti ini membantu Claude Code menulis komentar dan handoff yang ramah pemula.

Contoh Cloudflare Workers yang bisa disalin

Worker berikut sengaja dibuat kecil. /api/edge-content membaca negara dari metadata Cloudflare atau header test lokal, mengubahnya menjadi locale, lalu menyimpan respons selama 60 detik dengan Cache API. Header CF-IPCountry membuat cabang wilayah bisa dites dengan curl sebelum deploy.

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

Detail paling penting adalah cache key yang berisi locale. Tanpa itu, CTA Jepang bisa dikembalikan ke pengunjung Indonesia atau Inggris. Query string juga dihapus agar parameter seperti utm_source tidak memecah cache menjadi banyak entry yang tidak berguna.

Memperluas pola ke Vercel dan Deno

Vercel Edge Middleware berguna sebelum halaman dirender. Ia bisa menambah header, menyimpan bucket A/B, dan melakukan redirect berdasarkan wilayah. Tetap perhatikan batasan Edge Runtime dan hindari paket yang membutuhkan API khusus 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";
}

Di Deno Deploy, pertahankan bentuk Web API dengan Request dan Response, tetapi jangan menyalin field khusus Cloudflare seperti request.cf. Header dan environment variable berbeda untuk tiap provider, jadi tulis dengan jelas di 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",
  });
});

Perintah verifikasi

Kode Edge perlu diverifikasi dari sisi type, HTTP lokal, cabang wilayah, header cache, dan kesiapan deploy. Minta Claude Code meninggalkan bukti ini di handoff, bukan hanya menulis “sudah diimplementasikan”.

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

Jalankan curl di terminal lain.

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

Perilaku yang diharapkan sederhana: request pertama untuk locale dan path tertentu mengembalikan X-Edge-Cache: MISS; request berikutnya mengembalikan HIT. JP menjadi ja, US menjadi en, dan query tracking tidak membuat entry cache terpisah.

Kesalahan yang sering terjadi

Kesalahan pertama adalah menaruh terlalu banyak pekerjaan di Edge. Panggilan LLM panjang, ORM berat, PDF, konversi gambar, dan billing kompleks biasanya lebih cocok untuk origin API atau queue. Edge adalah pintu masuk, bukan seluruh backend.

Kesalahan kedua adalah cache key yang terlalu luas atau terlalu sempit. Jika locale, status login, tampilan harga, atau bucket eksperimen mengubah respons, semuanya harus masuk ke key. Jika noise seperti utm_* atau timestamp masuk ke key, cache hampir tidak pernah hit.

Kesalahan ketiga adalah terlalu percaya pada geografi. request.cf.country dan x-vercel-ip-country bagus untuk default pengalaman, tetapi bukan bukti untuk pajak, umur, izin, atau billing. VPN, proxy kantor, dan routing CDN bisa mengubah negara yang terlihat.

Kesalahan keempat adalah memberi Claude Code hanya nama provider. “Buat dengan Workers” tidak menjelaskan apakah kamu ingin Cache API, KV, D1, kompatibilitas Vercel, atau fallback ke origin. Untuk menentukan batas, bandingkan dengan Claude Code serverless functions dan optimasi performa Claude Code.

Jalur revenue dan langkah berikutnya

Untuk situs konten multibahasa, Edge runtime juga bisa memperbaiki jalur revenue. Kamu bisa menampilkan copy PDF gratis sesuai bahasa, mengarahkan pembaca ke CTA produk yang tepat, menormalkan parameter iklan sebelum cache, dan menjaga CTA template tetap cepat.

Untuk materi yang bisa dipakai ulang, lihat produk ClaudeCodeLab. Jika tim ingin menstandarkan prompt, aturan review, dan batas antara Edge dan Node, lihat pelatihan dan konsultasi Claude Code. Untuk alur singkat, mulai dari cheat sheet gratis.

Hasil yang benar-benar dicoba

Dalam pembaruan ini, Masa menguji sample Workers lokal dengan mengganti CF-IPCountry: JP dan CF-IPCountry: US, lalu mengecek locale, X-Edge-Cache, dan cache key yang menghapus parameter tracking. Temuan pentingnya: pada verifikasi lokal, header test perlu dibaca sebelum request.cf.country; kalau tidak, cabang negara bisa terlihat seperti menempel saat dicek berulang. Cache key juga memakai /__edge-cache/${locale}${pathname} agar konten regional tidak bercampur. Saat memberi brief ke Claude Code, minta review prioritas header, cabang wilayah, dan cache key secara bersamaan.

Ringkasan

Edge computing bukan memindahkan semuanya ke Edge. Ini adalah desain yang menaruh keputusan request kecil dekat pengguna, sementara pekerjaan berat dan keputusan final tetap berada di API normal. Beri Claude Code batas runtime, aturan cache key, cabang wilayah, dan perintah verifikasi sejak awal. Hasilnya bukan hanya cepat, tetapi juga mudah direview.