Immutable solution version
itty-router on Workers: tiny router without the framework traps
Complete solution
Shows how to fix itty-router on Workers: tiny router without the framework traps. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
It fits Workers well because it is plain functions over the standard Request/Response, exactly what the runtime hands you.
import { Router } from 'itty-router';
const router = Router();
router.get('/api/records/:id', async (request, env) => {
const { id } = request.params;
const row = await env.DB.prepare('SELECT * FROM records WHERE id = ?').bind(id).first();
return Response.json(row);
});
router.all('*', () => new Response('Not found', { status: 404 }));
export default {
fetch: (request, env, ctx) => router.handle(request, env, ctx),
};Steps
- itty-router is a minimal router (a few hundred bytes) for the Workers runtime. No build config, no framework ceremony. It fits Workers well because it is plain functions over the standard Request/Response, exactly what the runtime hands you.
import { Router } from 'itty-router';
const router = Router();
router.get('/api/records/:id', async (request, env) => {
const { id } = request.params;
const row = await env.DB.prepare('SELECT * FROM records WHERE id = ?').bind(id).first();
return Response.json(row);
});
router.all('*', () => new Response('Not found', { status: 404 }));
export default {
fetch: (request, env, ctx) => router.handle(request, env, ctx),
};- Note the second argument: itty-router passes extra
handlearguments through to handlers, soenv(andctx) are available in every route. Forgetting to forwardenvfrom the fetch handler is the classic itty-router-on-Workers bug; bindings then read as undefined. - - Forward
(request, env, ctx)fromfetchintorouter.handle, always.
- Add a catch-all 404 route; without one, unmatched requests fall through silently.
- Keep the router module-scope but read
envper request (same isolate-reuse caution as any Worker).
When to use
You are seeing this: itty-router is a minimal router (a few hundred bytes) for the Workers runtime. Use this skill when you run into "itty-router on Workers: tiny router without the framework traps".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
Why this happens
The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.
Evidence
Runtime behavior grounded in Cloudflare Workers docs: the fetch handler signature (request, env, ctx) and env bindings model from https://developers.cloudflare.com/workers/runtime-apis/bindings/; itty-router API (Router, request.params, handle forwarding) from the itty-router project README at https://github.com/kwhitley/itty-router
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_bSAVzBQGydIFLC-8H28cCw" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">itty-router on Workers: tiny router without the framework traps <span>— Vectle</span></a>