cloudflare-qr-redirect

A lightweight, edge-based QR code redirect service built on Cloudflare Workers. Achieve sub-50ms redirects globally with built-in scan analytics.

Why?

Most QR code services run redirects through their main app server, resulting in:

• Cold starts on serverless (500ms+)
• Single region latency
• Slow database queries on every scan

This worker runs at the edge in 300+ cities worldwide. Every scan hits the nearest edge node for instant redirects.

Features

• Sub-50ms redirects globally via Cloudflare's edge network
• Geo tracking using request.cf (city, country, coordinates) — no external API needed
• Device detection from User-Agent parsing
• Async logging — redirect fires immediately, analytics logged in background via ctx.waitUntil()
• 302 redirects (not 301) so destination URL changes take effect immediately
• Zero npm dependencies — uses only Cloudflare Workers built-in APIs + Supabase REST

Architecture

User scans QR → Cloudflare Worker (edge) → 302 redirect to destination
                        ↓ (async, non-blocking)
                  Log scan event to Supabase
                  (device, city, country, timestamp)

Setup

1. Clone this repo
2. Copy wrangler.toml.example to wrangler.toml
3. Set your Supabase credentials as Worker secrets:

npx wrangler secret put SUPABASE_URL
npx wrangler secret put SUPABASE_ANON_KEY

4. Create the required tables in Supabase:

CREATE TABLE qr_codes (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  short_slug VARCHAR(10) UNIQUE NOT NULL,
  destination_url TEXT NOT NULL,
  status VARCHAR(20) DEFAULT 'active',
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE scan_events (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  qr_id UUID REFERENCES qr_codes(id),
  scanned_at TIMESTAMPTZ DEFAULT NOW(),
  device_type VARCHAR(20),
  os_type VARCHAR(50),
  ip_city VARCHAR(100),
  ip_country VARCHAR(100),
  user_agent TEXT
);

5. Deploy:

npx wrangler deploy

How it works

302 not 301

We use 302 (temporary) redirects because users can change their destination URL anytime. A 301 would get cached by browsers, making URL changes invisible to returning visitors.

Free geo data

Cloudflare's request.cf object provides city, country, latitude, and longitude on every request — no external geo API needed. This powers scan analytics at zero extra cost.

Async logging

We don't await the database insert for scan events. The redirect fires immediately, and analytics data gets logged in the background using ctx.waitUntil(). Users get their redirect in ~40ms.

Performance

Metric	Value
Average redirect time	~40ms
Cold starts	None (Cloudflare Workers)
Global edge locations	300+
Infrastructure cost	~$5/month

Used in production

This redirect architecture powers OwnQR — a $15 one-time dynamic QR code generator for small businesses.

License

MIT