Cloudflare Workers Router

Cloudflare Workers Router is a super lightweight router (1.3K gzipped) with middleware support and ZERO dependencies for Cloudflare Workers.

When I was trying out Cloudflare Workers I almost immediately noticed how fast it was compared to other serverless offerings. So I wanted to build a full-fledged API to see how it performs doing real work, but since I wasn't able to find a router that suited my needs I created my own.

I worked a lot with Express.js in the past and really enjoyed their middleware approach, but since none of the available Cloudflare Worker routers offered middleware support at the time, I felt the need to create this router.

Features
Usage
Reference
Setup

Features

ZERO dependencies
Lightweight (1.3K gzipped)
Fully written in TypeScript
Integrated Debug-Mode & CORS helper
Built specifically around Middlewares

Usage

TypeScript Example

import { Router } from '@tsndr/cloudflare-worker-router'

export interface Env {
    // Example binding to KV. Learn more at https://developers.cloudflare.com/workers/runtime-apis/kv/
    // MY_KV_NAMESPACE: KVNamespace
    //
    // Example binding to Durable Object. Learn more at https://developers.cloudflare.com/workers/runtime-apis/durable-objects/
    // MY_DURABLE_OBJECT: DurableObjectNamespace
    //
    // Example binding to R2. Learn more at https://developers.cloudflare.com/workers/runtime-apis/r2/
    // MY_BUCKET: R2Bucket
}


// Initialize router
const router = new Router<Env>()

// Enabling build in CORS support
router.cors()

// Register global middleware
router.use(({ req, res, next }) => {
    res.headers.set('X-Global-Middlewares', 'true')
    next()
})

// Simple get
router.get('/user', ({ req, res }) => {
    res.body = {
        data: {
            id: 1,
            name: 'John Doe'
        }
    }
})

// Post route with url parameter
router.post('/user/:id', ({ req, res }) => {

    const userId = req.params.id

    // Do stuff...

    if (errorDoingStuff) {
        res.status = 400
        res.body = {
            error: 'User did stupid stuff!'
        }
        return
    }

    res.status = 204
})

// Delete route using a middleware
router.delete('/user/:id', ({ req, res, next }) => {

    if (!apiTokenIsCorrect) {
        res.status = 401
        return
    }

    await next()
}, (req, res) => {

    const userId = req.params.id

    // Do stuff...
})

// Listen Cloudflare Workers Fetch Event
export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        return router.handle(env, request)
    }
}

JavaScript Example

import { Router } from '@tsndr/cloudflare-worker-router'

// Initialize router
const router = new Router()

// Enabling build in CORS support
router.cors()

// Register global middleware
router.use(({ req, res, next }) => {
    res.headers.set('X-Global-Middlewares', 'true')
    next()
})

// Simple get
router.get('/user', ({ req, res }) => {
    res.body = {
        data: {
            id: 1,
            name: 'John Doe'
        }
    }
})

// Post route with url parameter
router.post('/user/:id', ({ req, res }) => {

    const userId = req.params.id

    // Do stuff...

        if (errorDoingStuff) {
            res.status = 400
            res.body = {
                error: 'User did stupid stuff!'
            }
            return
        }

    res.status = 204
})

// Delete route using a middleware
router.delete('/user/:id', ({ req, res, next }) => {

    if (!apiTokenIsCorrect) {
        res.status = 401
        return
    }

    await next()
}, (req, res) => {

    const userId = req.params.id

    // Do stuff...
})

// Listen Cloudflare Workers Fetch Event
export default {
    async fetch(request, env) {
        return router.handle(env, request)
    }
}

Reference

`router.debug([state = true])`

Enable or disable debug mode. Which will return the error.stack in case of an exception instead of and empty 500 response. Debug mode is disabled by default.

`state`

State is a boolean which determines if debug mode should be enabled or not (default: true)

Key	Type	Default Value
`state`	`boolean`	`true`

`router.use([...handlers])`

`handler(ctx)`

Handler is a function which will be called for every request.

`ctx`

Object containing env, req, res, next

`router.cors([config])`

If enabled will overwrite other OPTIONS requests.

`config` (object, optional)

Key	Type	Default Value
`allowOrigin`	`string`	`*`
`allowMethods`	`string`	`*`
`allowHeaders`	`string`	`*`
`maxAge`	`integer`	`86400`
`optionsSuccessStatus`	`integer`	`204`

Supported Methods

router.any(url, [...handlers])
router.connect(url, [...handlers])
router.delete(url, [...handlers])
router.get(url, [...handlers])
router.head(url, [...handlers])
router.options(url, [...handlers])
router.patch(url, [...handlers])
router.post(url, [...handlers])
router.put(url, [...handlers])
router.trace(url, [...handlers])

`url` (string)

The URL starting with a /. Supports the use of dynamic parameters, prefixed with a : (i.e. /user/:userId/edit) which will be available through the req-Object (i.e. req.params.userId).

`handlers` (function, optional)

An unlimited number of functions getting req and res passed into them.

`ctx`-Object

Key	Type	Description
`env`	`object`	Environment
`req`	`req`-Object	Request Object
`res`	`res`-Object	Response Object
`next`	`next`-Handler	Next Handler

`req`-Object

Key	Type	Description
`body`	`object` / `string`	Only available if method is `POST`, `PUT`, `PATCH` or `DELETE`. Contains either the received body string or a parsed object if valid JSON was sent.
`headers`	`Headers`	Request Headers Object
`method`	`string`	HTTP request method
`params`	`object`	Object containing all parameters defined in the url string
`query`	`object`	Object containing all query parameters

`res`-Object

Key	Type	Description
`body`	`object` / `string`	Either set an `object` (will be converted to JSON) or a string
`headers`	`Headers`	Response Headers Object
`status`	`integer`	Return status code (default: `204`)
`webSocket`	`WebSocket`	Upgraded websocket connection

Setup

Please follow Cloudflare's Get started guide to install wrangler.

Initialize Project

wrangler init <name>

Use of TypeScript is strongly encouraged :)

npm i -D @tsndr/cloudflare-worker-router

TypeScript (`src/index.ts`)

import { Router } from '@tsndr/cloudflare-worker-router'

export interface Env {
  // Example binding to KV. Learn more at https://developers.cloudflare.com/workers/runtime-apis/kv/
  // MY_KV_NAMESPACE: KVNamespace
  //
  // Example binding to Durable Object. Learn more at https://developers.cloudflare.com/workers/runtime-apis/durable-objects/
  // MY_DURABLE_OBJECT: DurableObjectNamespace
  //
  // Example binding to R2. Learn more at https://developers.cloudflare.com/workers/runtime-apis/r2/
  // MY_BUCKET: R2Bucket
}

const router = new Router<Env>()

/// Example Route
//
// router.get('/hi', ({ res }) => {
//    res.body = 'Hello World'
// })


/// Example Route for splitting into multiple files
//
// const hiHandler: RouteHandler<Env> = ({ res }) => {
//     res.body = 'Hello World'
// }
//
// router.get('/hi', hiHandler)


// TODO: add your routes here

export default {
    async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
        return router.handle(env, request)
    }
}

JavaScript (`src/index.js`)

Consider using TypeScript instead :)

import { Router } from '@tsndr/cloudflare-worker-router'

const router = new Router()

// router.get(/'hi', ({ res }) => {
//    res.body = 'Hello World'
//}

// TODO: add your routes here

export default {
    async fetch(request, env, ctx) {
        return router.handle(env, request)
    }
}

noman-land / cloudflare-worker-router Goto Github PK

cloudflare-worker-router's Introduction

Cloudflare Workers Router

Contents

Features

Usage

TypeScript Example

Reference

router.debug([state = true])

state

router.use([...handlers])

handler(ctx)

ctx

router.cors([config])

config (object, optional)

Supported Methods

url (string)

handlers (function, optional)

ctx-Object

req-Object

res-Object

Setup

Initialize Project

TypeScript (src/index.ts)

JavaScript (src/index.js)

cloudflare-worker-router's People

Contributors

Watchers

Recommend Projects

Recommend Topics

Recommend Org