Get unlimited public & private packages + team-based management with npm Teams.Learn more »


1.7.0 • Public • Published

Cloudworker Router

A small (3,36KB) koajs-router-style router for cloudflare workers.

  • Express style routing with router.get, ..
  • Named URL paramters
  • Route based on hosts and headers,
  • Multiple route middlewares
  • ES7 async/await support


npm install cloudworker-router --save

Basic Usage

The idea is to make the router work as closely to the koajs-router as possible, partly because it's a tried and tested module but also to make the learning curve as flat as possible.

Basic example with GET request

const Router = require('cloudworker-router');

router.get('/', async (ctx) => {
    ctx.body = 'Hello World';
    ctx.status = 200;

addEventListener('fetch', event => {

The router exposes get, post, patch and del methods as shorthands for the most common use cases. For examples of their usage, see the example folder. HEAD requests are handled automatically by the router.

For more examples on usage and deployment see the examples folder in the project.

Defining paths

The paths are translated to regular expressions for matching. Query strings are not considred when matching requests.

Named router paramteres are captured and added to ctx.params :

router.get('/hello/:name', async (ctx) => {
    ctx.status = 200
    ctx.body = 'Hello ' +;

router.get('/:wildcard*', async (ctx) => {
    ctx.status = 200;
    ctx.body = ctx.params.wildcard; // Will return the whole path

For routing on other properties than the method or the path the routes can be added using the router.add function:

    host: '', // Defaults to .*
    path: '/hello', Defaults to .*
    method: ['GET', 'HEAD'], // Defaults to ['GET']
}, async (ctx) => {
    ctx.status = 200;
    ctx.body = 'Hello world';

Named parameters can be added to the host property as well and are the values are also added to ctx.params:

    host: '',
    path: '/hello',
    method: ['GET', 'HEAD'],
}, async (ctx) => {
    ctx.status = 200;
    ctx.body = ctx.params.sub; // Will contain the subdomain from the request

As Cloudflare adds country codes to the request headers it's possible to route the request based on geo or any other header passed by the client:

    path: '/hello',
    method: ['GET'],
    headers: {
      'cf-ipcountry': 'SE'
}, async (ctx) => {
    ctx.status = 200;
    ctx.body = 'Hello Sweden!!';


The context encapsulates the request and the response object.

A new context instance are created for each request.

An example of a context object created for a request:

  request: {
    headers: {
      accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
      accept-encoding: "gzip",
      accept-language: "en-GB,en-US;q=0.9,en;q=0.8,es;q=0.7",
      cf-connecting-ip: "",
      cf-ipcountry: "ES",
      cf-ray: "50ac448ca95ed685",
      cf-visitor: "{"scheme":"http"}",
      connection: "Keep-Alive",
      cookie: "__cfduid=dee52228d3848ca5abc16f5c6be4640981565603001",
      host: "",
      upgrade-insecure-requests: "1",
      user-agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.87 Safari/537.36",
      x-forwarded-proto: "http",
      x-real-ip: ""
    href: "",
    host: "",
    hostname: "",
    method: "GET",
    origin: "",
    path: "/ctx",
    protocol: "http",
    query: {
      foo: "bar"
    querystring: "foo=bar",
    search: "?foo=bar
  event: {
    request: {
      cf: {
        tlsVersion: "",
        httpProtocol: "HTTP/1.1",
        tlsCipher: "",
        asn: 3352,
        requestPriority: "",
        clientTrustScore: 91,
        country: "ES",
        tlsClientAuth: {
          certIssuerDNLegacy: "",
          certIssuerDN: "",
          certIssuerDNRFC2253: "",
          certSubjectDNLegacy: "",
          certVerified: "NONE",
          certNotAfter: "",
          certSubjectDN: "",
          certFingerprintSHA1: "",
          certNotBefore: "",
          certSerial: "",
          certPresented: "0",
          certSubjectDNRFC2253: ""
        colo: "MAD"
      fetcher: {

      redirect: "manual",
      headers: {

      url: "",
      method: "GET",
      bodyUsed: false,
      body: null
    type: "fetch"
  state: {
    handlers: []
  response: {
    headers: {

  body: "",
  status: 404,
  query: {
    foo: "bar"
  params: {}

The name all invoced handlers is stored in an array in the state for debugging purposes.

Cloudflare specifics

Chunked encoding

By default cloudflare uses chunked encoding. Content-Length headers are not allowed in chunked responses according to the http-spec so they are automatically removed by cloudflare. If the worker respondes directly with a buffer rather than streaming the response cloudflare will automatically add/overwrite with a correct Content-Length header.

Head requests

If a worker respondes with a body to a head request cloudflare will remove the body and set the correct Content-Length headers. From a router perspective the head requests are handled just like get requests.


npm i cloudworker-router

DownloadsWeekly Downloads






Unpacked Size

297 kB

Total Files


Last publish


  • avatar