itty-router

Tiny (the router alone is >500 bytes), zero-dependency router - built for Cloudflare Workers, but works everywhere!

This router avoids all assumptions about how or where you'll use it, what you'll return with it, etc. It specifically chooses a linear flow-through route-matching pattern to allow the most power and flexibility in middleware chaining (including other routers for nested APIs). By giving you complete control over the routes, middleware chain, and downstream handling, you can even make your own, more opinionated router with itty at the core, for a mere ~500 bytes.

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
}

Full Documentation

For complete API documentation, please visit itty.dev.

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