README.md

wkrk

Fast and lightweight framework for Cloudflare Workers

👩‍🚒 Features

• Simple routing system.
• Handy helpers that return native Request and Response objects for maximum compatibility.
• TypeScript support.
• No build tools.

Installation

npm: npm i wkrk

yarn: yarn add wkrk

Getting Started

To get started, simply export a call to the wkrk function with your routes. Let's start with a route that responds to the /users path:

// index.js
import { wkrk } from "wkrk";
import users from "./api/users";

const routes = { "/users": users };

export default wkrk(routes);

Then define a simple handler for GET requests:

// api/users.js
export default {
  get({ req, res }) {
    return res.status(200).json({ name: "Giovanni" });
  },
};

You can also define everything in a single file:

import { wkrk } from "wkrk";

const routes = {
  "/users": {
    get({ req, res }) {
      return res.status(200).json({ name: "Giovanni" });
    },
  },
};

export default wkrk(routes);

Although working on a single file works, we highly recommend to separate your routes into multiple files and join them in your main index file:

import { wkrk } from "wkrk";
import users from "./api/users";
import posts from "./api/posts";

const routes = {
  "/users": users,
  "/posts": posts,
};

export default wkrk(routes);

Handling HTTP Methods

You can add the following functions to your routes:

• get: Handles GET requests.
• post: Handles POST requests.
• put: Handles PUT requests.
• delete: Handles DELETE requests.
• handler: Handles all requests that aren't defined by any function above.

You can combine handler with the other functions. An example of this is shown below:

export default {
  get({ req, res }) {
    return res.status(200).json({ name: "Giovanni" });
  },
  handler({ req, res }) {
    return res.status(200).send("I match everything except GET requests.");
  },
};

Extensions

Every handler has two parameters: req and res. res provides handy methods that returns a native Request object that your Workers already understand.

res.json({ name: "Giovanni" });
res.status(200).json({ name: "Giovanni" });
res.status(200).send("I return some plain text");

// Set the content type to text/html and return some data
res.set("Content-Type", "text/html");
res.send("<p>Hello World!</p>");

How it Works

wkrk does not do any magic, it's just syntactic sugar for your workers ✨

As an example, the following:

import { wkrk } from "wkrk";

const routes = {
  "/users": {
    get({ req, res }) {
      return res.status(200).json({ name: "Giovanni" });
    },
  },
};

export default wkrk(routes);

Is equivalent to:

export default {
  async fetch(request: Request): Promise<Response> {
    if (request.method === "GET") {
      const json = JSON.stringify({ name: "Giovanni" });
      return new Response(json);
    }

    return new Response("I don't know how to handle this request", {
      status: 500,
    });
  },
};

File System Routing

API routes are great and are used by frameworks like Next.js and NuxtJS. However, read the file system it's not possible. An alternative to this is to provide a compiler that pulls this data and generates the configuration for your router. However, I choosed to keep it simple for now and avoid overcomplicate things in the very beginning.