Pokédex at the Edge

// 01 — The problem

Every lookup is slow and repetitive if you hit the origin every time.

Answering kalob.io/pokemon/@charizard means resolving a name to a Pokémon ID, fetching that Pokémon's record, its species record, and its evolution chain — up to four separate calls to PokeAPI for one page. Doing that on every single visit is slow, and it leans on someone else's free API far more than it needs to.

The brief going in was simple: build the whole thing as a Cloudflare Worker, store results in Cloudflare KV instead of standing up a database, and cache aggressively — seven days per entry — so repeat lookups come straight from the edge.

Try it

// 03 — Technical insights

Why Cloudflare KV instead of a database

This data doesn't need a database's guarantees. Pokémon sprites and evolution chains barely change, there's no relational querying to do, and the only access pattern is "fetch by a known key." Cloudflare KV — a key-value store built into the same account as the Worker — fits that shape exactly: no schema to design, no connection pool to manage, no server to provision, and it's replicated globally so a cached entry written near one edge location is readable from the rest.

The cache key is deliberately layered instead of one flat blob per page: the shared name index, each species record, and each evolution chain are all cached independently from the final rendered page. That's what lets two different slugs pointing at the same species — Meowstic and its female form — reuse each other's cached lookups instead of duplicating them.

async function cached(kv, key, load) {
  const fullKey = "pokemon:v1:" + key;
  const existing = await kv.get(fullKey, "json");
  if (existing !== null) return { value: existing, hit: true };

  const value = await load();
  if (value !== null) {
    // 7-day TTL — no cron job, no manual purge. The entry just expires.
    await kv.put(fullKey, JSON.stringify(value), { expirationTtl: 7 * 24 * 60 * 60 });
  }
  return { value, hit: false };
}

Every layer — the page, the index, each species, each evolution chain — calls this same helper with its own key. The first deploy still shipped a bug: PokeAPI's own fetch calls used redirect: "error", which looks reasonable coming from browser JavaScript but throws inside a Worker, since the edge runtime only implements follow and manual. Live log streaming with wrangler tail surfaced the exact TypeError within a minute of reloading the page, and switching to redirect: "manual" plus a response.ok check fixed it without touching anything KV-related.

// 04 — Results

A warm lookup never leaves Cloudflare's edge.

// 05 — What I learned

// Technology used