How Workers Routes Work

Understand this first: a Cloudflare Worker intercepts HTTP requests via a route pattern. Your origin receives a normal request. Zero backend changes. Every other demo on this site works exactly this way.

The Problem

""We can't add features — our backend team is fully booked for 6 months.""

The Outcome

0

lines changed on your origin server. The Worker is deployed independently on Cloudflare — your backend never knows it exists.

Live demo below

Core concept

Your origin never knows a Worker exists.

0

backend changes

10s

to deploy

330

cities globally

Request path
Response path
🌐

Browser

user request

⚡ Cloudflare Edge

330 cities, 125+ countries

Route Match

*shoplegacy.com/*

🤖 Worker

① Request phase

○ await fetch(origin)

② Response phase

○ HTMLRewriter.transform()

🏢

Your Origin

unchanged

○ Request sent○ Route matched○ Worker intercepts○ Origin responds○ Worker transforms○ Enhanced delivered

Live comparison

Same URL. Two completely different experiences.

Left: origin only, no Worker. Right: Worker route active — AI chatbot injected at the edge via HTMLRewriter. The origin code is identical in both.

shoplegacy.com/products/chairNo Worker
🪑

STRANDMON Wing Chair

SKU: STR-4892

$299.00

High-back wing chair for great support. Perfect for reading and relaxing.

❌ No chatbot

Questions? Email support@shoplegacy.com

Reply time: 3–5 business days

shoplegacy.com/products/chair
Worker route active
🪑

STRANDMON Wing Chair

SKU: STR-4892

$299.00

High-back wing chair for great support. Perfect for reading and relaxing.

AI Assistantinjected by Worker · origin untouched
Hi! Ask me anything about this product.

How to do this

1

✏️ Write a Worker

A TypeScript file. Check the path, fetch from origin, transform the response. Guard non-HTML paths so binary assets pass through.

2

🗺 Add a route

One line in wrangler.toml. Wildcards supported. Multiple routes per Worker.

3

🚀 Deploy

wrangler deploy. Live globally in 10 seconds. Rollback is one command too.

wrangler.toml — route configuration (the only file you add)
# wrangler.toml — the only file you add to your project
name             = "my-worker"
main             = "worker.ts"
compatibility_date = "2026-04-23"

# Workers AI binding — gives the Worker access to 50+ AI models
[ai]
binding = "AI"

# Route — Worker runs IN FRONT of an existing origin (your backend).
# Use this when your origin already exists (Pages, Workers, S3, EC2, your VPS).
# Requires a proxied DNS record for the hostname (orange-cloud in Cloudflare DNS).
[[routes]]
pattern   = "*shoplegacy.com/*"   # wildcards supported
zone_name = "shoplegacy.com"      # your zone in Cloudflare

# Alternative: Custom Domain — use when the Worker IS the origin
# (no upstream server). Cloudflare auto-creates the DNS + SSL cert.
# [[routes]]
# pattern       = "store.shoplegacy.com"
# custom_domain = true

# ─── Nothing else changes ────────────────────────────────────────
# Your origin server code:    untouched
# Your DNS A/CNAME records:   untouched (proxied record required)
# Your SSL certificate:       untouched
# Your database:              untouched
# Your existing deployments:  untouched
✓ unchangedYour DNS A/CNAME records✓ unchangedYour origin server code✓ unchangedYour SSL certificate✓ unchangedYour database✓ unchangedYour existing deployments

What else this same route can do

🔍

Semantic Search

Intercept /api/search → Vectorize

See demo →

💬

AI Chatbot

HTMLRewriter injects chat widget

See demo →

⚡

KV Edge Caching

Cache responses, skip origin 98%

See demo →

🌏

Geo Localisation

Local prices from request.cf.*

See demo →

Productionising this

What changes when you ship this for real

Custom Domain vs Route

Route = Worker runs in front of an existing origin. Custom Domain = Worker IS the origin (no upstream). Pick deliberately — see /try for the canonical setup.

Proxied DNS required

Routes only fire on Cloudflare-managed zones with a proxied (orange-cloud) DNS record for the hostname. Without it: ERR_NAME_NOT_RESOLVED.

Bypass header for fetch loops

When a Worker fetches its own route, set X-Worker-Bypass: 1 and skip the transform on re-entry. The /try chatbot Worker demonstrates this.

Wildcards & specificity

More specific routes win: shop.com/admin/* beats shop.com/*. Use this for staged rollouts — route 10% of traffic to v2 via path prefix.

Observability per route

Enable observability = { enabled = true } in wrangler.toml. Workers Logs filters by Worker name — every Route hit is traceable.

Compatibility date

New features (AI Search binding, etc.) require a recent compatibility_date. Bump per-Worker, never silently — old code may rely on the old runtime semantics.