DEV Community: dk

Bootstrapping Cloudflare Workers app with oak framework & routing controller

dk — Sun, 30 Jun 2024 01:57:39 +0000

Hello all,

Following up on my previous introductory post about the library oak-routing-ctrl, I'd love to share an npm script that generates a boilerplate code-base with the following tools built-in:

oak framework (middleware framework)
oak-routing-ctrl (TypeScript decorator for API scaffolding)
Cloudflare Workers application development kit (wrangler)

Part 1: Bootstrapping

npm create oak-cloudflare-worker@latest

This script will ask us a few setup preferences, such as:

project directory (we can leave empty to use the current directory)
project meta i.e. name, version, author, etc. - basically the things we'd normally declare in the package.json file

Once the last step is confirmed, we'd have a project directory ready to work on. Here's the folder structure:

|____.npmrc
|____.gitignore
|____package.json
|____tsconfig.json
|____wrangler.toml
|____src
  |____index.ts
  |____CfwController.ts

Part 2: Developing

We can now install the dependencies (as declared in package.json) with e.g.:

npm i

Executing npm run dev will start the "Worker" on local:

⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8787
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit                                      │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Assuming we use the template example provided in the boilerplate (CfwController.ts), then we can communicate with the Worker like so:

curl http://localhost:8787/echo/devto

{"query":{},"body":{},"param":{"name":"devto"},"headers":{"accept":"*/*","accept-encoding":"br, gzip","host":"localhost:8787","user-agent":"curl/8.6.0"}}

Part 3: Deploying

To deploy to Cloudflare, one way is simply running

npm run deploy

which will guide us through the Cloudflare authentication flow until the application is fully "uploaded" to Cloudflare.

Alternatively, if we don't like going through the authentication flow all the time, we can get a Cloudflare API token. Note that, at the minimum, we'll need the permissions to manage "Workers" resources. I chose these for my example:

With the token, one can add it to the env var and run the deployment script e.g. like so:

CLOUDFLARE_API_TOKEN=your-cloudflare-api-token npm run deploy

Closing words

I hope the script

npm create oak-cloudflare-worker@latest

may help you bootstrap your Cloudflare Workers project with ease. It is obviously opinionated on the oak and oak-routing-ctrl libraries, but also there's nothing preventing one from switching to another supporting framework (or writing everything from scratch).

If 'starting from scratch' is your flavour, you can also execute npm create cloudflare@latest (as documented) to start off with an almost-empty Cloudflare Workers project.

In parallel, a GitHub code template also exists as an alternative to running npm create oak-cloudflare-worker.

For transparency: the source code for the npm create script itself is hosted here.

If you've created or plan to create something cool with this script, your story would be so much appreciated in the comment section below 🙏. If you got an idea to improve the script, I'm all ears here, or you may simply suggest a PR!

I wish you enjoyments in your next projects 🍺🍺🍺

Scaffolding API projects easily with oak-routing-ctrl

dk — Thu, 20 Jun 2024 22:06:19 +0000

Greetings to Deno / TypeScript / JavaScript community!

Today I'd love to introduce a DevTool: oak-routing-ctrl

Now if you read the link above & still are unsure what this tool does, then I hope this article may help 😀

Let's say you:

wanna build a microservice that provides a set of API to your consumers
chose the oak framework as your HTTP middleware library
do not want to write repeated routing code for all your API endpoints

Then oak-routing-ctrl might be worth a try.

Here is what's in the box:

1. TypeScript Decorators

First we have a set of TypeScript Decorators (conforming to TC39 proposal) that makes it straightforward to declare API endpoints & assign it to a handler function in a few lines of code:

// MyController.ts

import { Controller, Get } from "@dklab/oak-routing-ctrl@0.9.0";

@Controller()
export class MyController {
  @Get()
  doSomething() {
    return "hello, dev.to";
  }
}

2. An initiation helper function

Now to actually spin up an HTTP server, we'll need to initiate the server instance e.g. with the middleware oak, and glue it up with the API route handler function we wrote above. Of course it can be in the same file, or a different file, up to your flavour. Here we use a different file:

// main.ts

import { Application } from "@oak/oak@16.1.0";
import { useOakServer } from "@dklab/oak-routing-ctrl@0.9.0";
import { MyController } from "./MyController.ts";

const app = new Application();
useOakServer(app, [MyController]);
await app.listen({ port: 1993 });

The example code so far assumes we're on Deno runtime. But heads up: both oak and oak-routing-ctrl fully support other runtimes (Bun, Cloudflare Workers, and Node.js).

With Deno assumed, let's start our server up:

deno run --allow-env --allow-net main.ts

And send a test cURL:

curl localhost:1993
# prints: hello, dev.to

That was the most simple form of it. More complex examples are available in the README.

Looking forward...

Up to this point, you may wonder what's so special about this library. I, as the author, am of course biased, but if you must know: nope, it's indeed "just another DevTool". I'm not taking pride in its superb performance or any underlying rocket science, I do appreciate the level of care and seriousness I myself put in while developing it. Before it reached the "relatively stable" version of 0.7.4 (at which time I wrote this blog post), it had gone through a valley of alpha releases:

I don't intend to put much more logic in it from this point on. After using it on production for a while, I'll bump it to 1.0.0. It's released under MIT & anyone can contribute or even fork their own development directions.

What I commit to is the continuous maintenance of this library. It is used on production for my own and my employer's web-scale products, thereby giving me "unfair incentives" to keep it sane & performant.

If you use it for your work, I would really love to hear your thoughts and suggestions, i.e. what you like, what you don't like. A GitHub Star, or a constructive feedback issue, to me is equally valuable.

If I still have you on this line, it means my English skill is not any more rusty than my coding skill ;) and it means the world to me (😀). If you feel I missed something, or said something contrary to your knowledge, please feel free to place your questions in the comment section down below. Discussing tech topics is the best way for everyone to learn!

Thank you for your time on this blog post. Have a blast in what you're doing, wherever you are 🍻