Project nine, URL shortener

Prerequisites and companion example

You need Node.js 22, pnpm, and the repository dependencies. The example lives in examples/url-shortener and uses local KV emulation only; it touches no remote state. Copy the local secret and start the Worker:

cp examples/url-shortener/.dev.vars.example examples/url-shortener/.dev.vars
pnpm wrangler dev --config examples/url-shortener/wrangler.jsonc

In another terminal, run node --test examples/url-shortener/test/index.test.mjs; eight tests should pass. Then create a link with the curl commands in the example README; the response status should be 201, and curl -i http://127.0.0.1:8787/<slug> should return 302 with a Location header pointing at the target URL. For background on bindings and secrets, see Bindings and secrets.

Design and data model

One Worker plus one KV namespace (binding name LINKS) is enough. The KV key is the slug, and the value is a JSON document: {url, clicks, createdAt, expiresAt}. Expiry uses the native KV expirationTtl, so expired keys disappear on their own with no scheduled job. The API surface has three endpoints:

Slugs must match ^[a-zA-Z0-9_-]{1,64}$, and target URLs are limited to the http: and https: protocols, which keeps schemes such as javascript: from being weaponized through redirects.

Implementing the core endpoints

The create path authenticates first, then validates the URL, the TTL, and the slug in order; a duplicate slug returns a stable 409 slug_taken. Random slugs come from crypto.getRandomValues, with a retry on collision:

const SLUG_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;

function parseTargetUrl(value) {
  if (typeof value !== 'string') return null;
  try {
    const url = new URL(value);
    return url.protocol === 'http:' || url.protocol === 'https:' ? url.toString() : null;
  } catch {
    return null;
  }
}

function randomSlug(length = 6) {
  const alphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
  const bytes = crypto.getRandomValues(new Uint8Array(length));
  return Array.from(bytes, (byte) => alphabet[byte % alphabet.length]).join('');
}

The redirect path reads the JSON, increments clicks, writes it back, then answers 302. The write recomputes the remaining expirationTtl from expiresAt so a click does not erase the expiry. Remember that KV is eventually consistent: this read-modify-write counter can lose concurrent increments, and reads may lag behind edge caching, so the click count is an approximation suited to trend watching, not billing. Redirect responses carry cache-control: no-store so every visit passes through the Worker; for the full caching discussion, see Cache rules as the first policy.

KV or D1

Short links are a classic read-heavy workload, and both stores work. The trade-off is consistency and query power:

Pick KV when you want fast redirects, a simple shape, and approximate counts; pick D1 when you need exact counts, rich reports, or relational data. For a systematic chooser, see Storage chooser.

Abuse prevention and security boundaries

A public creation endpoint will be abused: put Turnstile in front of the human-facing creation flow, add WAF rate limiting per IP, and treat both as complements to the server-side ADMIN_KEY guard, not replacements. Configuration details are in Turnstile and WAF. Also reserve the /api/ prefix for system routes before user slugs are matched, so nobody can register a slug that hijacks an API path.

Mature projects to study

Short links have been built repeatedly in the Cloudflare ecosystem; read these before writing your own:

• miantiao-me/Sink (7,000+ stars): a Nuxt 3 full-stack shortener with links in KV and visit analytics in Analytics Engine, supporting custom slugs, UTM parameters, expiry, access passwords, and QR codes, under AGPL-3.0; the project migrated from ccbikai/Sink.
• xyTom/Url-Shorten-Worker (1,700+ stars): a single-file Worker plus KV, small enough to read end to end; it added captcha-based abuse protection in 2025.
• x-dr/short (400+ stars): a Chinese-language project built on Pages Functions plus D1, a useful counterpoint to the KV design in this guide.

Verification and troubleshooting

Remote boundaries and rollback

Creating the remote KV namespace, writing production secrets, and deploying the Worker all modify Cloudflare state, and this tutorial does not automate them. Rollback of a deployment does not delete link data already written to KV, nor does it restore a deleted namespace: export or record the critical slug mappings before rolling back, verify that core short links still redirect afterwards, and only delete or recreate a namespace once you have confirmed no production traffic depends on it.

Next: Set cache rules as the first policy for redirects and static assets.

Official sources

• Cloudflare KV
• Cloudflare Workers