Building a Self-Hosted URL Shortener with Cloudflare Workers

Full URL with UTM: 155 characters
https://iamdevbox.com/posts/building-complete-oidc-login-flow-urls/?utm_source=twitter&utm_medium=social&utm_campaign=blog_post

Available for content: Only 125 characters

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    // Handle short URL redirects
    if (url.pathname.startsWith('/s/')) {
      return handleRedirect(url, env);
    }

    // Handle API: create short URL
    if (url.pathname === '/api/shorten') {
      return handleCreate(request, env);
    }

    // Handle API: get statistics
    if (url.pathname.startsWith('/api/stats/')) {
      return handleStats(url, env);
    }

    return new Response('Not Found', { status: 404 });
  }
};

async function handleRedirect(url, env) {
  const code = url.pathname.split('/s/')[1];

  // Get mapping from KV
  const mapping = await env.URL_MAPPINGS.get(code, { type: 'json' });

  if (!mapping) {
    return new Response('Short URL not found', { status: 404 });
  }

  // Build target URL with UTM parameters
  const targetUrl = new URL(mapping.url);
  const source = url.searchParams.get('s') || 'short';

  targetUrl.searchParams.set('utm_source', source);
  targetUrl.searchParams.set('utm_medium', 'shortlink');
  targetUrl.searchParams.set('utm_campaign', mapping.campaign || 'general');

  // Track stats asynchronously
  trackAccess(code, source, env);

  // 301 permanent redirect
  return Response.redirect(targetUrl.toString(), 301);
}

async function handleCreate(request, env) {
  // Verify API key
  const authHeader = request.headers.get('Authorization');
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return new Response('Unauthorized', { status: 401 });
  }

  const apiKey = authHeader.substring(7);
  if (apiKey !== env.API_KEY) {
    return new Response('Invalid API key', { status: 401 });
  }

  const body = await request.json();
  const { url: longUrl, code, campaign } = body;

  // Generate or use provided short code
  const shortCode = code || generateCode();

  // Store in KV
  await env.URL_MAPPINGS.put(shortCode, JSON.stringify({
    url: longUrl,
    campaign: campaign || 'general',
    created: new Date().toISOString()
  }));

  return Response.json({
    shortUrl: `https://example.com/s/${shortCode}`,
    code: shortCode,
    longUrl
  });
}

function generateCode() {
  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
  let code = '';
  for (let i = 0; i < 6; i++) {
    code += chars[Math.floor(Math.random() * chars.length)];
  }
  return code;
}

async function trackAccess(code, source, env) {
  const statsKey = `stats:${code}`;
  const stats = await env.URL_MAPPINGS.get(statsKey, { type: 'json' }) || {
    total: 0,
    sources: {}
  };

  stats.total++;
  stats.sources[source] = (stats.sources[source] || 0) + 1;
  stats.lastAccess = new Date().toISOString();

  await env.URL_MAPPINGS.put(statsKey, JSON.stringify(stats));
}

name = "url-shortener"
main = "worker.js"
compatibility_date = "2024-01-01"

[[kv_namespaces]]
binding = "URL_MAPPINGS"
id = "YOUR_KV_NAMESPACE_ID"

[[routes]]
pattern = "yourdomain.com/s/*"
zone_name = "yourdomain.com"

[[routes]]
pattern = "yourdomain.com/api/shorten"
zone_name = "yourdomain.com"

[[routes]]
pattern = "yourdomain.com/api/stats/*"
zone_name = "yourdomain.com"

# Install Wrangler CLI
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Create KV namespace
wrangler kv:namespace create URL_MAPPINGS

# Set API key (for authentication)
wrangler secret put API_KEY

# Deploy
wrangler deploy

import os
import requests
from typing import Optional

class URLShortener:
    def __init__(self, api_key: Optional[str] = None):
        self.api_key = api_key or os.getenv('SHORTENER_API_KEY')
        self.api_endpoint = 'https://yourdomain.com/api/shorten'

    def create(self, long_url: str, code: Optional[str] = None,
               campaign: str = 'blog_post') -> Optional[str]:
        if not self.api_key:
            return None

        try:
            response = requests.post(
                self.api_endpoint,
                json={
                    'url': long_url,
                    'code': code,
                    'campaign': campaign
                },
                headers={'Authorization': f'Bearer {self.api_key}'},
                timeout=10
            )

            if response.status_code == 200:
                return response.json()['shortUrl']
        except Exception as e:
            print(f'Error creating short URL: {e}')

        return None

def shorten_url_for_twitter(long_url: str) -> str:
    """Create short URL with automatic fallback"""
    shortener = URLShortener()
    short_url = shortener.create(long_url)

    # Fallback to simplified UTM if shortening fails
    return short_url if short_url else f'{long_url}?utm_source=twitter'

from url_shortener import shorten_url_for_twitter

# Original URL (115 characters)
url = 'https://example.com/posts/building-self-hosted-url-shortener-cloudflare-workers/'

# Shortened URL (32 characters)
short = shorten_url_for_twitter(url)
# Result: https://example.com/s/abc123

# Character savings: 83 characters (72% reduction)
print(f'Saved {len(url) - len(short)} characters!')

name: Auto Publish

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup URL Shortener
        run: |
          echo "SHORTENER_API_KEY=${{ secrets.SHORTENER_API_KEY }}" >> $GITHUB_ENV

      - name: Publish to Twitter
        run: |
          python3 publish.py --use-short-urls

San Francisco  → <10ms
Shanghai       → <15ms
London         → <12ms
Tokyo          → <8ms
Singapore      → <10ms

shortener.create(
    long_url='https://example.com/posts/oauth-guide/',
    code='oauth'  # Custom code
)
# Result: https://example.com/s/oauth

curl https://example.com/api/stats/abc123

{
  "total": 142,
  "sources": {
    "twitter": 98,
    "linkedin": 32,
    "direct": 12
  },
  "lastAccess": "2025-11-27T10:30:00Z"
}