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

• Tiny. The Router itself is ~440 bytes gzipped, and the entire library is under 1.6k!
• Easy to use. We believe route code should be self-evident, obvious, and read more like poetry than code.
• Agnostic. We leave you with full control over response types, matching order, upstream/downstream effects, etc.
• Works anywhere, in any environment.
• Fully typed/TypeScript support, including hinting.
• Parses route params, optional params, wildcards, greedy params, and file formats.
• Automatic query parsing.
• Easy error handling, including throwing errors with HTTP status codes!
• Easy Response creation, with helpers for major formats (e.g. json, html, png, jpeg, etc.)
• Deep APIs via router nesting.
• Full middleware support. Includes the following by default:
  • withParams - access the params directly off the Request (instead of request.params).
  • withCookies - access cookies in a convenient Object format.
  • withContent - auto-parse Request bodies as request.content.
  • CORS - because we love you.
• Fully readable regex... yeah right! 😆

Full Documentation

Complete documentation/API is available at itty.dev, or join our Discord channel to chat with community members for quick help!

Installation

npm install itty-router

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 a gift basket?

Join us on Discord!

Testing and Contributing

• Fork repo
• Install dev dependencies via yarn
• Start test runner/dev mode yarn dev
• Add your code and tests if needed - do NOT remove/alter existing tests
• Commit files
• Submit PR (and fill out the template)
• 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