cloudflare-worker-base

# Cloudflare Worker Base Stack

**Production-tested**: cloudflare-worker-base-test (https://cloudflare-worker-base-test.webfonts.workers.dev)
**Last Updated**: 2025-11-25
**Status**: Production Ready ✅

---

## Table of Contents

1. [Quick Start (5 Minutes)](#quick-start-5-minutes)
2. [The Four-Step Setup Process](#the-four-step-setup-process)
3. [Known Issues Prevention](#known-issues-prevention)
4. [Configuration Files Reference](#configuration-files-reference)
5. [When to Load References](#when-to-load-references)

---

## Quick Start (5 Minutes)

### 1. Scaffold Project

```bash
npm create cloudflare@latest my-worker -- \
  --type hello-world \
  --ts \
  --git \
  --deploy false \
  --framework none
```

**Flags:** `--type hello-world` (clean start), `--ts` (TypeScript), `--git` (init repo), `--deploy false` (configure first), `--framework none` (add Vite manually)

### 2. Install Dependencies

```bash
cd my-worker
bun add hono@4.10.6  # preferred
# or: npm add hono@4.10.6
bun add -d @cloudflare/vite-plugin@1.15.2 vite@latest wrangler@4.50.0
# or: npm add -d @cloudflare/vite-plugin@1.15.2 vite@latest wrangler@4.50.0
```

**Version Notes:**
- `hono@4.10.6`: Minimum recommended version (verified 2025-11-20)
- `@cloudflare/vite-plugin@1.15.2`: Minimum recommended version, includes HMR fixes
- `wrangler@4.50.0`: Latest stable version (verified 2025-11-23)
- `vite`: Latest version compatible with Cloudflare plugin

### 3. Configure Wrangler

Create or update `wrangler.jsonc`:

```jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "account_id": "YOUR_ACCOUNT_ID",
  "compatibility_date": "2025-10-11",
  "observability": {
    "enabled": true
  },
  "assets": {
    "directory": "./public/",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application",
    "run_worker_first": ["/api/*"]
  }
}
```

**CRITICAL: `run_worker_first` Configuration**
- Without this, SPA fallback intercepts API rou