itty-router

---

4.x Documentation @ itty.dev

---

Itty aims to be the world's smallest (~440 bytes), feature-rich JavaScript router, enabling beautiful API code with a near-zero bundlesize. Designed originally for Cloudflare Workers, itty can be used in browsers, Service Workers, edge functions, or standalone runtimes like Node, Bun, etc.!

Features:

• fully typed/TypeScript support
• route params (including optional params)
• wildcards and greedy params
• query parsing
• middleware
• router nesting
• lightweight, easy-to-understand route code
• works in virtually any runtime/environment (including the browser)

Full Documentation

Complete docs/API are available at itty.dev, or join our Discord channel to chat!

Installation

npm install itty-router@next

Example

import { 
  error,                  // creates error responses
  json,                   // creates json responses
  Router,                 // the ~440 byte router itself
  withParams,             // middleware: puts params directly on the Request
} from 'itty-router'

const router = Router()   // create a new Router
const todos = []          // and some fake todos

router
  // middleware: withParams auto-parses route params into the request
  .all('*', withParams) 

  // GET list of todos
  .get('/todos', () => todos)

  // GET single todo, by ID
  .get('/todos/:id', 
    ({ id }) => todos.find(todo => todo.id === id) 
                || error(404, 'That todo was not found')
  )

  // 404 for everything else
  .all('*', () => error(404))

// Example: Cloudflare Worker module syntax
export default {
  fetch: (request, ...args) => router
                                 .handle(request, ...args)
                                 .then(json)    // automatically send as JSON
                                 .catch(error)  // and send error Responses for thrown errors
}

Join the Discussion!

Have a question? Suggestion? Complaint? Want to send me a gift basket?

Join us on Discord!

Testing and Contributing

1. Fork repo
2. Install dev dependencies via yarn
3. Start test runner/dev mode yarn dev
4. Add your code and tests if needed - do NOT remove/alter existing tests
5. Verify that tests pass once minified yarn verify
6. Commit files
7. Submit PR with a detailed description of what you're doing
8. I'll add you to the credits! :)

Special Thanks

This repo goes out to my past and present colleagues at Arundo - who have brought me such inspiration, fun, and drive over the last couple years. In particular, the absurd brevity of this code is thanks to a clever [abuse] of Proxy, courtesy of the brilliant @mvasigh. This trick allows methods (e.g. "get", "post") to by defined dynamically by the router as they are requested, drastically reducing boilerplate.

Contributors

These folks are the real heroes, making open source the powerhouse that it is! Help out and get your name added to this list! <3

Core Concepts

• @mvasigh - proxy hack wizard behind itty, coding partner in crime, maker of the entire doc site, etc, etc.
• @hunterloftis - router.handle() method now accepts extra arguments and passed them to route functions
• @SupremeTechnopriest - improved TypeScript support and documentation! :D

Code Golfing

• @taralx - router internal code-golfing refactor for performance and character savings
• @DrLoopFall - v4.x re-minification

Fixes & Build

• @taralx - QOL fixes for contributing (dev dep fix and test file consistency) <3
• @technoyes - three kind-of-a-big-deal errors fixed. Imagine the look on my face... thanks man!! :)
• @roojay520 - TS interface fixes
• @jahands - v4.x TS fixes

Documentation

• @arunsathiya, @poacher2k, @ddarkr, @kclauson, @jcapogna