Home

Awesome

Cloudflare Workers Starter Kit

<a href="http://www.typescriptlang.org/"><img src="https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg?style=flat-square" height="20"></a> <a href="http://patreon.com/koistya"><img src="https://img.shields.io/badge/dynamic/json?color=%23ff424d&label=Patreon&style=flat-square&query=data.attributes.patron_count&suffix=%20patrons&url=https%3A%2F%2Fwww.patreon.com%2Fapi%2Fcampaigns%2F233228" height="20"></a> <a href="https://discord.gg/QEd934tZvR"><img src="https://img.shields.io/discord/643523529131950086?label=Chat&style=flat-square" height="20"></a> <a href="https://github.com/kriasoft/cloudflare-starter-kit/stargazers"><img src="https://img.shields.io/github/stars/kriasoft/cloudflare-starter-kit.svg?style=social&label=Star&maxAge=3600" height="20"></a> <a href="https://twitter.com/koistya"><img src="https://img.shields.io/twitter/follow/koistya.svg?style=social&label=Follow&maxAge=3600" height="20"></a>

Project template for scaffolding Cloudflare Workers projects.

Features


This project was bootstrapped with Cloudflare Starter Kit. Be sure to join our Discord channel for assistance.

Directory Structure

├──.github/workflows — CI/CD workflows powered by GitHub Actions<br> ├──.vscodeVSCode settings including code snippets, recommended extensions etc.<br> ├──api — Cloudflare Worker script for handling API requests<br> ├──app — Web application front-end powered by Vite and React.js<br> ├──edgeCloudflare Workers script for serving static websites (reverse proxy)<br> ├──scripts — Automation scripts, such as yarn deploy<br> ├──package.json — The list of NPM dependencies and Yarn workspaces<br> └──tsconfig.base.jsonTypeScript configuration shared across packages/workspaces<br>

Tech Stack

Requirements

Getting Started

Generate a new repository from this template, clone, install dependencies, open it in VSCode and start hacking:

$ git clone https://github.com/kriasoft/cloudflare-starter-kit.git
$ cd ./cloudflare-starter-kit
$ yarn install
$ yarn start
$ yarn test

Find the worker scripts inside of the ./edge and ./api folders.

IMPORTANT: Ensure that VSCode is using the workspace version of TypeScript.

Scripts

How to Create a CF Worker

Find below the minimal boilerplate for creating a new CF Worker script using TypeScript with ESM syntax:

example/index.ts — CF Worker script

import { Hono } from "hono";

const app = new Hono<Env>();

app.get("/", ({ text }) => {
  return text("Hello world!", 200);
});

export default app;

example/index.test.ts — unit test powered by Miniflare

import { expect, test } from "vitest";
import app from "./index.js";

test("GET /", async () => {
  const req = new Request(`https://${env.APP_HOSTNAME}/`);
  const res = await app.fetch(req, bindings);
  const body = await res.text();

  expect({ status: res.status, body }).toEqual({
    status: 200,
    body: "Hello world!",
  });
});

example/wrangler.toml — deployment configuration

name = "example"
main = "index.js"
compatibility_date = "2022-04-18"
account_id = "$CLOUDFLARE_ACCOUNT_ID"
route = "$APP_HOSTNAME/*"

[vars]
APP_ENV = "$APP_ENV"
APP_HOSTNAME = "$APP_HOSTNAME"

[[rules]]
type = "ESModule"
globs = ["**/*.js"]

Plus package.json, tsconfig.json, and global.d.ts files configuring TypeScript for the workspace.

Note that $APP_HOSTNAME and $CLOUDFLARE_ACCOUNT_ID placeholders in the example above will be automatically replaced with values from *.env files for the target environment during local testing or deployment.

For more sophisticated examples visit Cloudflare Workers Examples directory.

How to Deploy

The deployments are handled automatically by GitHub Actions (see .github/workflows) whenever a new commit lands onto one of these branches:

Alternatively, you can deploy the app manually by ensuring the all the required environment variables found in the *.env files are up-to-date (e.g. CLOUDFLARE_API_TOKEN), then running yarn deploy [--env #0], specifying the target deployment area via --env flag, e.g. --env=test (default) or --env=prod.

You can also deploy packages (workspaces) individually, for example:

$ yarn api:deploy --env=prod
$ yarn edge:deploy --env=prod
<p align="center"><img src="https://files.tarkus.me/cloudflare-workers-deploy.svg" /></p>

How to View Logs

$ yarn workspace api wrangler tail [--env #0]
$ yarn workspace api wrangler tail [--env #0]

How to Update

Backers 💰

<a href="https://reactstarter.com/b/1"><img src="https://reactstarter.com/b/1.png" height="60" /></a>  <a href="https://reactstarter.com/b/2"><img src="https://reactstarter.com/b/2.png" height="60" /></a>  <a href="https://reactstarter.com/b/3"><img src="https://reactstarter.com/b/3.png" height="60" /></a>  <a href="https://reactstarter.com/b/4"><img src="https://reactstarter.com/b/4.png" height="60" /></a>  <a href="https://reactstarter.com/b/5"><img src="https://reactstarter.com/b/5.png" height="60" /></a>  <a href="https://reactstarter.com/b/6"><img src="https://reactstarter.com/b/6.png" height="60" /></a>  <a href="https://reactstarter.com/b/7"><img src="https://reactstarter.com/b/7.png" height="60" /></a>  <a href="https://reactstarter.com/b/8"><img src="https://reactstarter.com/b/8.png" height="60" /></a>

Related Projects

How to Contribute

Anyone and everyone is welcome to contribute. Start by checking out the list of open issues marked help wanted. However, if you decide to get involved, please take a moment to review the guidelines.

License

Copyright © 2020-present Kriasoft. This source code is licensed under the MIT license found in the LICENSE file.


<sup>Made with ♥ by Konstantin Tarkus (@koistya, blog) and contributors.</sup>