cloudflare-full-stack-integration

# Cloudflare Full-Stack Integration Patterns

Production-tested patterns for React + Cloudflare Workers + Hono + Clerk authentication.

## When to Use This Skill

Use this skill when you need to:

- Connect a React frontend to a Cloudflare Worker backend
- Implement authentication with Clerk in a full-stack app
- Set up API calls that automatically include auth tokens
- Fix CORS errors between frontend and backend
- Prevent race conditions with auth loading
- Configure environment variables correctly
- Set up D1 database access from API routes
- Create protected routes that require authentication

## What This Skill Provides

### Templates

**Frontend** (`templates/frontend/`):
- `lib/api-client.ts` - Fetch wrapper with automatic token attachment
- `components/ProtectedRoute.tsx` - Auth gate pattern with loading states

**Backend** (`templates/backend/`):
- `middleware/cors.ts` - CORS configuration for dev and production
- `middleware/auth.ts` - JWT verification with Clerk
- `routes/api.ts` - Example API routes with all patterns integrated

**Config** (`templates/config/`):
- `wrangler.jsonc` - Complete Workers configuration with bindings
- `.dev.vars.example` - Environment variables setup
- `vite.config.ts` - Cloudflare Vite plugin configuration

**References** (`references/`):
- `common-race-conditions.md` - Complete guide to auth loading issues

## Critical Architectural Insights

### 1. @cloudflare/vite-plugin Runs on SAME Port

**Key Insight**: The Worker and frontend run on the SAME port during development.

```typescript
// ✅ CORRECT: Use relative URLs
fetch('/api/data')

// ❌ WRONG: Don't use absolute URLs or proxy
fetch('http://localhost:8787/api/data')
```

**Why**: The Vite plugin runs your Worker using workerd directly in the dev server. No proxy needed!

### 2. CORS Must Be Applied BEFORE Routes

```typescript
// ✅ CORRECT ORDER
app.use('/api/*', cors())
app.post('/api/data', handler)

// ❌ WRONG ORDER - Will cause CORS errors
app.post('/api/data', hand