Skip to content

Latest commit

 

History

History
206 lines (148 loc) · 10.2 KB

README.md

File metadata and controls

206 lines (148 loc) · 10.2 KB
Raw

Cloudflare Workers Starter Kit

Project template for scaffolding Cloudflare Workers projects.

Features

  • Supports multiple CF Workers within the same (mono)repo; using ES modules syntax
  • Pre-configured with TypeScript, Babel, Rollup, ESLint, Vitest, Prettier, Wrangler CLI, Miniflare
  • Pre-configured with local, test (staging/QA), and prod (production) environments
  • Pre-configured with local testing and debugging; loading environment variables from *.env files
  • Web Crypto API usage example for integrating with 3rd party services (Google Cloud, etc.)
  • Code snippets and other VSCode settings; CI/CD workflows with GitHub Actions

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
├──.vscode — VSCode settings including code snippets, recommended extensions etc.
├──api — Cloudflare Worker script for handling API requests
├──app — Web application front-end powered by Vite and React.js
├──edge — Cloudflare Workers script for serving static websites (reverse proxy)
├──scripts — Automation scripts, such as yarn deploy
├──package.json — The list of NPM dependencies and Yarn workspaces
└──tsconfig.base.json — TypeScript configuration shared across packages/workspaces

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

How to View Logs

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

How to Update

  • yarn set version stable — Bump Yarn to the latest version
  • yarn upgrade-interactive — Update Node.js modules (dependencies)
  • yarn dlx @yarnpkg/sdks vscode — Update TypeScript, ESLint, and Prettier settings in VSCode

Backers 💰

              

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.

Made with ♥ by Konstantin Tarkus (@koistya, blog) and contributors.