itty-router

---

v4.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'
import { todos } from './external/todos'

// create a new Router
const router = Router()   

router
  // add some middleware upstream on all routes
  .all('*', withParams) 

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

  // GET single todo, by ID
  .get('/todos/:id', 
    ({ id }) => todos.getById(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)    // send as JSON
                                 .catch(error)  // catch 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: 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