cloudflare-full-stack-integration
Production-tested patterns for wiring a React frontend to a Cloudflare Workers + Hono backend with Clerk authentication and D1, including an API client that attaches auth tokens automatically, a ProtectedRoute auth gate with loading states, CORS middleware for dev and production, Clerk JWT verification middleware, wrangler.jsonc bindings, .dev.vars environment variables, and @cloudflare/vite-plugin config (the Worker and frontend share one dev port, so relative /api URLs are correct). Use when connecting frontend to backend, implementing an auth flow, or troubleshooting CORS errors, 401 Unauthorized responses, auth tokens not passing, race conditions while auth is still loading, environment variable confusion, or D1 connection issues.
How do I install this agent skill?
npx skills add https://github.com/jackspace/claudeskillz --skill cloudflare-full-stack-integrationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides legitimate documentation and code templates for integrating Cloudflare Workers with React and Clerk. No malicious patterns, obfuscation, or dangerous execution methods were detected. All suggested dependencies are standard industry packages and no remote code execution patterns were found.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
4/4 files flagged
What does this agent skill do?
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 attachmentcomponents/ProtectedRoute.tsx- Auth gate pattern with loading states
Backend (templates/backend/):
middleware/cors.ts- CORS configuration for dev and productionmiddleware/auth.ts- JWT verification with Clerkroutes/api.ts- Example API routes with all patterns integrated
Config (templates/config/):
wrangler.jsonc- Complete Workers configuration with bindings.dev.vars.example- Environment variables setupvite.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.
// ✅ 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
// ✅ CORRECT ORDER
app.use('/api/*', cors())
app.post('/api/data', handler)
// ❌ WRONG ORDER - Will cause CORS errors
app.post('/api/data', handler)
app.use('/api/*', cors())
3. Auth Loading is NOT a Race Condition
Most "race conditions" are actually missing isLoaded checks:
// ❌ WRONG: Calls API before token ready
useEffect(() => {
fetch('/api/data') // 401 error!
}, [])
// ✅ CORRECT: Wait for auth to load
const { isLoaded, isSignedIn } = useSession()
useEffect(() => {
if (!isLoaded || !isSignedIn) return
fetch('/api/data') // Now token is ready
}, [isLoaded, isSignedIn])
4. Environment Variables Have Different Rules
Frontend (Vite):
- MUST start with
VITE_prefix - Defined in
.envfile - Access:
import.meta.env.VITE_VARIABLE_NAME
Backend (Workers):
- NO prefix required
- Defined in
.dev.varsfile (dev) or wrangler secrets (prod) - Access:
env.VARIABLE_NAME
5. D1 Bindings Are Always Available
D1 is accessed via bindings - no connection management needed:
// ✅ CORRECT: Direct access via binding
const { results } = await env.DB.prepare('SELECT * FROM users').run()
// ❌ WRONG: No need to "connect" first
const connection = await env.DB.connect() // This doesn't exist!
Step-by-Step Integration Guide
Step 1: Project Setup
# Create project with Cloudflare Workers + React
npm create cloudflare@latest my-app
cd my-app
# Install dependencies
npm install hono @clerk/clerk-react @clerk/backend
npm install -D @cloudflare/vite-plugin @tailwindcss/vite
Step 2: Configure Vite
Copy templates/config/vite.config.ts to your project root.
Key points:
- Includes
cloudflare()plugin - No proxy configuration needed
- Sets up path aliases for clean imports
Step 3: Configure Wrangler
Copy templates/config/wrangler.jsonc to your project root.
Update:
- Replace
namewith your app name - Add D1/KV/R2 bindings as needed
- Set
run_worker_first: ["/api/*"]for API routes
Step 4: Set Up Environment Variables
Create .dev.vars (gitignored):
CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
CLERK_SECRET_KEY=sk_test_xxxxx
Create .env for frontend:
VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
Step 5: Add CORS Middleware
Copy templates/backend/middleware/cors.ts to your backend.
Apply in your main worker file:
import { corsMiddleware } from './middleware/cors'
app.use('/api/*', (c, next) => corsMiddleware(c.env)(c, next))
CRITICAL: Apply this BEFORE defining routes!
Step 6: Add Auth Middleware
Copy templates/backend/middleware/auth.ts to your backend.
Apply to protected routes:
import { jwtAuthMiddleware } from './middleware/auth'
app.use('/api/protected/*', jwtAuthMiddleware(c.env.CLERK_SECRET_KEY))
Step 7: Set Up API Client
Copy templates/frontend/lib/api-client.ts to your frontend.
Use in your App component:
import { useApiClient } from '@/lib/api-client'
function App() {
useApiClient() // Set up token access
return <YourApp />
}
Step 8: Create Protected Routes
Copy templates/frontend/components/ProtectedRoute.tsx.
Use to wrap authenticated pages:
<ProtectedRoute>
<Dashboard />
</ProtectedRoute>
Step 9: Create API Routes
Copy templates/backend/routes/api.ts as a reference.
Pattern for all routes:
- Apply CORS first
- Apply auth middleware to protected routes
- Extract user ID from JWT payload
- Access D1/KV/R2 via env bindings
- Return typed JSON responses
Step 10: Test Integration
# Start dev server
npm run dev
# Both frontend and backend run on http://localhost:5173
# API routes: http://localhost:5173/api/*
# Frontend: http://localhost:5173/*
Common Issues and Solutions
Issue: 401 Unauthorized Errors
Symptom: API calls fail with 401 even though user is signed in
Cause: API called before Clerk session is loaded
Fix: Check isLoaded and isSignedIn before API calls
const { isLoaded, isSignedIn } = useSession()
if (!isLoaded || !isSignedIn) return // Wait for auth
See: references/common-race-conditions.md
Issue: CORS Errors
Symptom: "No 'Access-Control-Allow-Origin' header" errors
Causes:
- CORS middleware not applied
- CORS middleware applied after routes (wrong order)
- Origin not allowed in production
Fix:
// Apply BEFORE routes
app.use('/api/*', cors())
app.post('/api/data', handler)
For production, update corsProdMiddleware with your domain.
Issue: Environment Variables Not Working
Symptom: Variables are undefined in frontend or backend
Frontend Fix:
- Variables MUST start with
VITE_ - Must be in
.envfile (not.dev.vars) - Access:
import.meta.env.VITE_NAME
Backend Fix:
- Variables in
.dev.varsfor local dev - Use
wrangler secret put NAMEfor production - Access:
env.NAME
Issue: D1 Queries Fail
Symptom: Database queries throw errors
Causes:
- Binding not configured in wrangler.jsonc
- SQL syntax errors
- Not using parameterized queries
Fix:
// ✅ CORRECT: Parameterized query
await env.DB.prepare('SELECT * FROM users WHERE id = ?')
.bind(userId)
.run()
// ❌ WRONG: SQL injection risk
await env.DB.prepare(`SELECT * FROM users WHERE id = ${userId}`).run()
Issue: Token Not Attached to Requests
Symptom: Backend receives requests without Authorization header
Cause: Not using apiClient or not calling useApiClient() hook
Fix:
- Call
useApiClient()in App component - Use
apiClient.get()instead of rawfetch()
// In App.tsx
import { useApiClient } from '@/lib/api-client'
function App() {
useApiClient() // MUST call this
return <YourApp />
}
// In components
import { apiClient } from '@/lib/api-client'
const data = await apiClient.get('/api/data')
Integration Checklist
Before deployment, verify:
Frontend:
-
useApiClient()called in App component - All protected pages wrapped in
<ProtectedRoute> - Check
isLoadedbefore making API calls - Environment variables start with
VITE_ - Using
apiClientfor all API calls
Backend:
- CORS middleware applied BEFORE routes
- Auth middleware on
/api/protected/*routes - Environment variables in
.dev.vars(dev) and secrets (prod) - D1/KV/R2 bindings configured in wrangler.jsonc
- Using parameterized queries for D1
Config:
-
wrangler.jsonchas correct bindings -
vite.config.tsincludescloudflare()plugin -
.dev.varsexists and is gitignored -
.envexists for frontend vars -
run_worker_first: ["/api/*"]in wrangler.jsonc
Package Versions (Verified 2025-10-23)
All packages are current stable versions:
{
"@clerk/clerk-react": "5.53.3",
"@clerk/backend": "2.19.0",
"hono": "4.10.2",
"vite": "7.1.11",
"@cloudflare/vite-plugin": "1.13.14"
}
Official Documentation Links
- Cloudflare Vite Plugin: https://developers.cloudflare.com/workers/vite-plugin/
- Hono: https://hono.dev/
- Clerk: https://clerk.com/docs
- D1 Database: https://developers.cloudflare.com/d1/
- CORS on Workers: https://developers.cloudflare.com/workers/examples/cors-header-proxy/
Production Evidence
Patterns tested in:
- WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev)
- Multiple Jezweb client projects
- All templates verified working 2025-10-23
Token Efficiency
Without this skill: ~12k tokens + 2-4 integration errors With this skill: ~4k tokens + 0 errors Savings: ~67% tokens, 100% error prevention
Remember: Most integration issues are just missing isLoaded checks or wrong middleware order. Use the templates and follow the step-by-step guide!
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/jackspace/claudeskillz/cloudflare-full-stack-integration">View cloudflare-full-stack-integration on skillZs</a>