Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kriasoft/cloudflare-starter-kit

Template (boilerplate) repository for scaffolding Cloudflare Workers projects
https://github.com/kriasoft/cloudflare-starter-kit

boilerplate cdn cloudflare cloudflare-workers edge edge-computing firebase firebase-auth front-end frontend gcp hachathon jamstack miniflare scaffolding starter-kit template typescript vite webworker

Last synced: about 1 month ago
JSON representation

Template (boilerplate) repository for scaffolding Cloudflare Workers projects

Awesome Lists containing this project

README

        

# Cloudflare Workers Starter Kit





Project template for [scaffolding](https://github.com/kriasoft/cloudflare-starter-kit/generate)
[Cloudflare Workers](https://workers.cloudflare.com/) projects.

## Features

- Supports [multiple CF Workers](https://miniflare.dev/core/mount) within the same (mono)repo; using ES modules syntax
- Pre-configured with [TypeScript](https://typescriptlang.org/), [Babel](https://babeljs.io/),
[Rollup](https://rollupjs.org/), [ESLint](https://eslint.org/), [Vitest](https://vitest.dev/),
[Prettier](https://prettier.io/), [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/),
[Miniflare](https://miniflare.dev/)
- 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](https://developer.mozilla.org/en-US/docs/Web/API/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](https://github.com/kriasoft/cloudflare-starter-kit).
Be sure to join our [Discord channel](https://discord.gg/QEd934tZvR) for assistance.

## Directory Structure

`├──`[`.github/workflows`](./.github/workflows/) — CI/CD workflows powered by [GitHub Actions](https://github.com/features/actions)

`├──`[`.vscode`](.vscode) — [VSCode](https://code.visualstudio.com/) settings including code snippets, recommended extensions etc.

`├──`[`api`](./api) — Cloudflare Worker script for handling API requests

`├──`[`app`](./app) — Web application front-end powered by [Vite](https://vitejs.dev/) and [React.js](https://reactjs.org/)

`├──`[`edge`](./edge) — [Cloudflare Workers](https://workers.cloudflare.com/) script for serving static websites (reverse proxy)

`├──`[`scripts`](./scripts) — Automation scripts, such as `yarn deploy`

`├──`[`package.json`](./project.json) — The list of [NPM](https://www.npmjs.com/) dependencies and [Yarn](https://yarnpkg.com/) workspaces

`└──`[`tsconfig.base.json`](./tsconfig.base.json) — [TypeScript](https://www.typescriptlang.org/) configuration shared across packages/workspaces

## Tech Stack

- [TypeScript](https://www.typescriptlang.org/), [Cloudflare Workers](https://workers.cloudflare.com/),
[Hono](https://honojs.dev/)
- [Vite](https://vitejs.dev/), [Rollup](https://rollupjs.org/),
[Miniflare](https://miniflare.dev/), [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/),
[ESLint](https://eslint.org/), [Prettier](https://prettier.io/),
[Vitest](https://vitest.dev/), [Yarn](https://yarnpkg.com/) with PnP

## Requirements

- [Node.js](https://nodejs.org/) v18+ with [Corepack](https://nodejs.org/api/corepack.html) (`$ corepack enable`)
- [VS Code](https://code.visualstudio.com/) editor with [recommended extensions](.vscode/extensions.json)

## Getting Started

[Generate a new repository](https://github.com/kriasoft/cloudflare-starter-kit/generate)
from this template, clone, install dependencies, open it in VSCode and start hacking:

```bash
$ 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`](./edge/) and [`./api`](./api/) folders.

**IMPORTANT**: Ensure that VSCode is using the [workspace version of TypeScript](https://code.visualstudio.com/docs/typescript/typescript-compiling#_using-newer-typescript-versions).

## Scripts

- **`yarn start`** - Launches web application on [`http://localhost:5173/`](http://localhost:5173/)
- **`yarn lint`** — Validates the code using [ESLint](https://eslint.org/)
- **`yarn tsc`** — Validates the code using [TypeScript](https://www.typescriptlang.org/) compiler
- **`yarn test`** — Runs unit tests with [Vitest](https://vitest.dev/), [Miniflare](https://miniflare.dev/), and [Supertest](https://github.com/visionmedia/supertest)
- **`yarn build`** — Compiles and bundles worker scripts into the `./dist` folder(s)
- **`yarn deploy`** — Deploys the app to [Cloudflare Workers](https://developers.cloudflare.com/workers/) / [GCF](https://cloud.google.com/functions)

## 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

```ts
import { Hono } from "hono";

const app = new Hono();

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

export default app;
```

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

```ts
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

```toml
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`](./edge/package.json), [`tsconfig.json`](./edge/tsconfig.json),
and [`global.d.ts`](./edge/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`](./env/)
files for the target environment during local testing or deployment.

For more sophisticated examples visit [Cloudflare Workers Examples](https://developers.cloudflare.com/workers/examples/) directory.

## How to Deploy

The deployments are handled automatically by [GitHub Actions](https://github.com/features/actions)
(see [`.github/workflows`](.github/workflows/)) whenever a new commit lands onto
one of these branches:

- **`main`** — Deploys the app to [`https://test.example.com`](https://test.example.com/) (test/QA)
- **`release`** — Deploys the app to [`https://example.com`](https://example.com/) (production)

Alternatively, you can deploy the app manually by ensuring the all the
required environment variables found in the [`*.env`](./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:

```bash
$ 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

- [React Starter Kit](https://github.com/kriasoft/react-starter-kit) — front-end template for React and Relay using Jamstack architecture
- [Node.js API Starter Kit](https://github.com/kriasoft/node-starter-kit) — project template, pre-configured with Node.js, GraphQL, and PostgreSQL
- [GraphQL API and Relay Starter Kit](https://github.com/kriasoft/graphql-starter) — monorepo template, pre-configured with GraphQL API, React, and Relay

## How to Contribute

Anyone and everyone is welcome to [contribute](.github/CONTRIBUTING.md). Start
by checking out the list of [open issues](https://github.com/kriasoft/cloudflare-starter-kit/issues)
marked [help wanted](https://github.com/kriasoft/cloudflare-starter-kit/issues?q=label:"help+wanted").
However, if you decide to get involved, please take a moment to review the
[guidelines](.github/CONTRIBUTING.md).

## License

Copyright © 2020-present Kriasoft. This source code is licensed under the MIT license found in the
[LICENSE](https://github.com/kriasoft/cloudflare-starter-kit/blob/main/LICENSE) file.

---

Made with ♥ by Konstantin Tarkus ([@koistya](https://twitter.com/koistya), [blog](https://medium.com/@koistya))
and [contributors](https://github.com/kriasoft/cloudflare-starter-kit/graphs/contributors).