React SPA Cloudflare

This project is a pnpm monorepo with a client-side React SPA and a server-side Cloudflare Worker with KV storage. This project includes comprehensive testing, linting, and CI/CD setup, along with Sentry integration for error tracking.

Features

• React SPA for the client-side application
• Tailwind CSS for styling
• Tanstack Query for client http request state management
• Hono server-side api framework
• Prettier for code formatting
• ESLint for linting
• Vitest for unit testing
• Playwright for end-to-end testing
• TypeScript for type checking
• Cloudflare Pages for hosting the client, Worker with KV storage for hosting the server
• GitHub workflows for CI and staging deployment
• Sentry integration for client-side error tracking
• pnpm for performant monorepo package management

Getting Started

Pre-requisites

1. pnpm v9 and above
2. node v22.9.0 and above

Installation

1. Ensure you're using the correct version of Node:

   nvm use 22.9.0

2. If necessary, install the correct version of pnpm:

   npm i -g pnpm@9

3. Install dependencies

   pnpm i

Deployment Configuration

1. Follow instructions in README.cloudflare

2. Follow instructions in README.sentry

Deploying a branch to stage

1. Click the "Actions" tab
2. Select the "stage" workflow
3. Open the dropdown for "Run workflow" and select the branch you wish to deploy
4. Choose your deploy target (client, server, both)
5. Click "Run workflow"

The client app will deploy to the preview url, and the server will deploy to your staging worker.

Scripts

• pnpm run dev: Start the development server
• pnpm run lint: Run ESLint
• pnpm run test: Run unit tests with Vitest
• pnpm run typecheck: Run TypeScript type checking
• pnpm run format: Format code with Prettier
• pnpm run e2e: Run end-to-end tests with Playwright

Some convenience scripts for shortcuts:

• pnpm run clean: Execute a clean install of package dependencies
• pnpm run client <script>: Run a script within the client package only
• pnpm run server <script>: Run a script within the server package only

Debug

Server starts on wrong port locally

Sometimes the server fails to shutdown, leaving an instance listening to port 8787. The next time you run pnpm run server dev, it will start a new instance and listen to a random port. Running killall workerd does not seem to fix it. Instead, get any workerd process ID listening to port 8787 (there may be several) and kill it. On macOS:

lsof -i :8787
kill -9 <pid>