isabella232 / cloudflare-starter-kit

Template (boilerplate) repository for scaffolding Cloudflare Workers projects

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, Jest, 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.
├──env — Settings for local (dev), test (staging/QA), and prod (production) environments
├──api — Cloudflare Worker script for handling API requests
├──app — Web application front-end powered by Vite and React.js
├──site — 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
├──rollup.config.mjs — Rollup configuration for compiling and bundling CF Workers
└──tsconfig.base.json — TypeScript configuration shared across packages/workspaces

Tech Stack

Cloudflare Workers, Miniflare, Wrangler CLI, Vite, TypeScript, Babel, ESLint, Prettier, Jest, Yarn, Rollup.

Requirements

• Node.js v16.15.0 or newer, Yarn package manager
• VS Code editor with recommended extensions

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 ./site and ./api folders.

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

Scripts

• yarn start - Launches web application on http://localhost:3000/
• yarn lint — Validates the code using ESLint
• yarn tsc — Validates the code using TypeScript compiler
• yarn test — Runs unit tests with Jest, Miniflare, and Supertest
• yarn build — Compiles and bundles worker scripts into the ./dist folder(s)
• yarn deploy — Deploys the app to Cloudflare Workers / GCF
• yarn cf <workspace> — Wrangler CLI wrapper with support of *.env files

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

export default {
  async fetch(req, env, ctx) {
    return new Response(`Hello world!`, { status: 200 });
  },
} as Required<Pick<ExportedHandler<Env>, "fetch">>;

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

import worker from "./index.js";

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

  expect(res.status).toEqual(200);
  expect(body).toEqual(`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:

• main — Deploys the app to https://test.example.com (test/QA)
• release — Deploys the app to https://example.com (production)

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 site:deploy --env=prod

How to View Logs

$ yarn api:cf tail [--env #0]
$ yarn site:cf 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

• React Starter Kit — front-end template for React and Relay using Jamstack architecture
• Node.js API Starter Kit — project template, pre-configured with Node.js, GraphQL, and PostgreSQL
• GraphQL API and Relay Starter Kit — monorepo template, pre-configured with GraphQL API, React, and Relay

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.}