Bootstrapping Cloudflare Workers app with oak framework & routing controller
Tags: worker, typescript, oak, webhook
Published: 2024-06-30 01:57:39

Hello all,

Following up on my previous [introductory post about the library oak-routing-ctrl](https://dev.to/thesephi/scaffolding-api-projects-easily-with-oak-routing-ctrl-1pj), I'd love to share an **npm script** that generates a boilerplate code-base with the following tools built-in:

- [oak framework](https://oakserver.org/) (middleware framework)
- [oak-routing-ctrl](https://jsr.io/@dklab/oak-routing-ctrl) (TypeScript decorator for API scaffolding)
- [Cloudflare Workers](https://workers.cloudflare.com/) application development kit (wrangler)

---

## Part 1: Bootstrapping

```bash
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.:
```bash
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](https://github.com/Thesephi/oak-routing-ctrl-cloudflare-worker/blob/main/src/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
```bash
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](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/). Note that, at the minimum, we'll need the permissions to manage "Workers" resources. I chose these for my example:

![Example of Cloudflare API token permissions to manage Worker resources](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kjti73q0078gdroxaye0.png)

With the token, one can add it to the env var and run the deployment script e.g. like so:
```bash
CLOUDFLARE_API_TOKEN=your-cloudflare-api-token npm run deploy
```

---

## Closing words

I hope the script

```bash
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](https://developers.cloudflare.com/workers/get-started/guide/)) to start off with an almost-empty Cloudflare Workers project.

In parallel, a [GitHub code template](https://github.com/Thesephi/oak-routing-ctrl-cloudflare-worker) 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](https://github.com/Thesephi/create-oak-cloudflare-worker).

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](https://github.com/Thesephi/create-oak-cloudflare-worker/pulls)!

I wish you enjoyments in your next projects 🍺🍺🍺