Itty aims to be the world's smallest (430 bytes), feature-rich JavaScript router, enabling low-calorie code with a low-calorie bundlesize. Designed originally for Cloudflare Workers, itty can be used in browsers, Service Workers, edge functions, or standalone runtimes like Node!

Features:

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

Full Documentation

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

Installation

npm install itty-router@next

Example

import { 
  error,                  // create an error response
  respondWithError,       // downstream handler for thrown errors
  respondWithJSON,        // downstream handler to send data as JSON
  Router,                 // the ~470 byte router itself
  withParams,             // middleware to auto-embed route params
  notFound,               // create a 404
} from 'itty-router'

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

router
  // add some global 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) 
                || notFound('That todo was not found')
  )

  // 404 for everything else
  .all('*', notFound)

// Example: Cloudflare ESM Worker syntax
export default {
  fetch: (request, env, context) => router
                                      .handle(request, env, context)
                                      .then(respondWithJSON)    // automatically send as JSON
                                      .catch(respondWithError)  // 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