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
- 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), andprod
(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<br>
├──
.vscode
— VSCode 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>
├──
edge
— Cloudflare 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.json
— TypeScript configuration shared across packages/workspaces<br>
Tech Stack
- TypeScript, Cloudflare Workers, Hono
- Vite, Rollup, Miniflare, Wrangler CLI, ESLint, Prettier, Vitest, Yarn with PnP
Requirements
- Node.js v18+ with Corepack (
$ corepack enable
) - 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 ./edge
and ./api
folders.
IMPORTANT: Ensure that VSCode is using the workspace version of TypeScript.
Scripts
yarn start
- Launches web application onhttp://localhost:5173/
yarn lint
— Validates the code using ESLintyarn tsc
— Validates the code using TypeScript compileryarn test
— Runs unit tests with Vitest, Miniflare, and Supertestyarn build
— Compiles and bundles worker scripts into the./dist
folder(s)yarn deploy
— Deploys the app to Cloudflare Workers / GCF
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:
main
— Deploys the app tohttps://test.example.com
(test/QA)release
— Deploys the app tohttps://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 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
yarn set version stable
— Bump Yarn to the latest versionyarn upgrade-interactive
— Update Node.js modules (dependencies)yarn dlx @yarnpkg/sdks vscode
— Update TypeScript, ESLint, and Prettier settings in VSCode
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
- 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.
<sup>Made with ♥ by Konstantin Tarkus (@koistya, blog) and contributors.</sup>