gh-jezweb-claude-skills-skills-cloudflare-worker-base/references/architecture.md

Architecture Deep Dive

Last Updated: 2025-10-20

This document explains the architectural patterns used in Cloudflare Workers with Hono, Vite, and Static Assets.

---

Table of Contents

1. Export Patterns
2. Routing Architecture
3. Static Assets Integration
4. Bindings and Type Safety
5. Development vs Production

---

Export Patterns

The Correct Pattern (ES Module Format)

import { Hono } from 'hono'

const app = new Hono()

// Define routes...

// ✅ CORRECT: Export the Hono app directly
export default app

Why this works:

• Hono's app object already implements the fetch handler
• When Cloudflare calls your Worker, it automatically invokes app.fetch()
• This is the ES Module Worker format (modern, recommended)

The Incorrect Pattern (Causes Errors)

// ❌ WRONG: This causes "Cannot read properties of undefined (reading 'map')" error
export default {
  fetch: app.fetch
}

Why this fails:

• When using Vite's build tools with Hono, the app.fetch binding is lost
• The Vite bundler transforms the code in a way that breaks the this context
• Source: honojs/hono #3955

Module Worker Format (When You Need Multiple Handlers)

import { Hono } from 'hono'

const app = new Hono()

// Define routes...

// ✅ CORRECT: Use Module Worker format for scheduled/tail handlers
export default {
  fetch: app.fetch,

  scheduled: async (event, env, ctx) => {
    // Cron job logic
    console.log('Cron triggered:', event.cron)
  },

  tail: async (events, env, ctx) => {
    // Tail handler logic
    console.log('Tail events:', events)
  }
}

When to use this:

• You need scheduled (cron) handlers
• You need tail handlers for log consumption
• You need queue consumers
• You need durable object handlers

Important: This is still ES Module format, not the deprecated Service Worker format.

Deprecated Service Worker Format (Never Use)

// ❌ DEPRECATED: Never use this format
addEventListener('fetch', (event) => {
  event.respondWith(handleRequest(event.request))
})

Why never use this:

• Deprecated since Cloudflare Workers v2
• Doesn't support modern features (D1, Vectorize, etc.)
• Not compatible with TypeScript types
• Not supported by Vite plugin

---

Routing Architecture

Request Flow

Incoming Request
    ↓
    ├─→ Worker checks run_worker_first patterns
    │   └─→ Matches /api/* → Worker handles it → Returns JSON
    │
    └─→ No match → Static Assets handler
        ├─→ File exists → Returns file
        └─→ File not found → SPA fallback → Returns index.html

Configuration Required

In wrangler.jsonc:

{
  "assets": {
    "directory": "./public/",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application",
    "run_worker_first": ["/api/*"]
  }
}

Critical: Without run_worker_first, the SPA fallback intercepts ALL requests, including API routes.

Route Priority

1. Worker routes (if matched by run_worker_first)

   app.get('/api/hello', (c) => c.json({ ... }))
   

2. Static files (if file exists in public/)

   public/styles.css → Served as-is
   public/logo.png → Served as-is
   

3. SPA fallback (if file doesn't exist)

   /unknown-route → Returns public/index.html
   

Advanced Routing Patterns

Wildcard Routes

// Match all API versions
app.get('/api/:version/users', (c) => {
  const version = c.req.param('version')
  return c.json({ version })
})

// Match nested routes
app.get('/api/users/:id/posts/:postId', (c) => {
  const { id, postId } = c.req.param()
  return c.json({ userId: id, postId })
})

Regex Routes

// Match numeric IDs only
app.get('/api/users/:id{[0-9]+}', (c) => {
  const id = c.req.param('id')
  return c.json({ id: parseInt(id) })
})

Route Groups

const api = new Hono()

api.get('/users', (c) => c.json({ users: [] }))
api.get('/posts', (c) => c.json({ posts: [] }))

app.route('/api', api)  // Mount at /api

---

Static Assets Integration

How Static Assets Work

1. Upload: When you deploy, Wrangler uploads public/ to Cloudflare's asset store
2. Binding: Your Worker receives an ASSETS Fetcher binding
3. Request: Your Worker can forward requests to ASSETS.fetch()
4. Cache: Assets are cached at the edge automatically

The Fallback Pattern

// Handle all unmatched routes
app.all('*', (c) => {
  // Forward to Static Assets
  return c.env.ASSETS.fetch(c.req.raw)
})

What this does:

• Forwards request to Static Assets handler
• Static Assets checks if file exists
• If yes: Returns file
• If no: Returns index.html (SPA fallback)

Custom 404 Handling

app.all('*', async (c) => {
  const response = await c.env.ASSETS.fetch(c.req.raw)

  // If Static Assets returns 404, customize response
  if (response.status === 404) {
    return c.json({ error: 'Not Found' }, 404)
  }

  return response
})

Asset Preprocessing

app.all('*', async (c) => {
  const url = new URL(c.req.url)

  // Rewrite /old-path to /new-path
  if (url.pathname === '/old-path') {
    url.pathname = '/new-path'
  }

  // Create new request with modified URL
  const modifiedRequest = new Request(url, c.req.raw)
  return c.env.ASSETS.fetch(modifiedRequest)
})

---

Bindings and Type Safety

Defining Bindings

type Bindings = {
  ASSETS: Fetcher               // Static Assets (always present)
  MY_KV: KVNamespace            // KV namespace
  DB: D1Database                // D1 database
  MY_BUCKET: R2Bucket           // R2 bucket
  MY_VAR: string                // Environment variable
}

const app = new Hono<{ Bindings: Bindings }>()

Accessing Bindings

app.get('/api/data', async (c) => {
  // Type-safe access to bindings
  const value = await c.env.MY_KV.get('key')
  const result = await c.env.DB.prepare('SELECT * FROM users').all()
  const object = await c.env.MY_BUCKET.get('file.txt')
  const variable = c.env.MY_VAR

  return c.json({ value, result, object, variable })
})

Auto-Generated Types

Run wrangler types to generate worker-configuration.d.ts:

// Auto-generated by Wrangler
interface Env {
  ASSETS: Fetcher
  MY_KV: KVNamespace
  DB: D1Database
  MY_BUCKET: R2Bucket
  MY_VAR: string
}

Then use:

const app = new Hono<{ Bindings: Env }>()

---

Development vs Production

Local Development (wrangler dev)

npm run dev

What happens:

• Miniflare simulates Cloudflare's runtime locally
• Bindings are emulated (KV, D1, R2)
• HMR enabled via Vite plugin
• Runs on http://localhost:8787

Configuration:

// vite.config.ts
export default defineConfig({
  plugins: [
    cloudflare({
      persist: true,  // Persist data between restarts
    }),
  ],
})

Production Deployment (wrangler deploy)

npm run deploy

What happens:

• Vite builds your code
• Wrangler uploads to Cloudflare
• Static Assets uploaded separately
• Worker deployed to edge network

Build Output:

dist/
├── index.js        # Your Worker code (bundled)
└── ...             # Other build artifacts

Environment-Specific Configuration

// wrangler.jsonc
{
  "name": "my-worker",
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "vars": { "ENV": "staging" },
      "kv_namespaces": [
        { "binding": "MY_KV", "id": "staging-kv-id" }
      ]
    },
    "production": {
      "name": "my-worker-production",
      "vars": { "ENV": "production" },
      "kv_namespaces": [
        { "binding": "MY_KV", "id": "production-kv-id" }
      ]
    }
  }
}

Deploy to specific environment:

wrangler deploy --env staging
wrangler deploy --env production

Environment Detection in Code

app.get('/api/info', (c) => {
  const isDev = c.req.url.includes('localhost')
  const env = c.env.ENV || 'development'

  return c.json({ isDev, env })
})

---

Performance Considerations

Cold Starts

Cloudflare Workers have extremely fast cold starts (~5ms):

• Code is distributed globally
• No containers to spin up
• Minimal initialization overhead

Keep your bundle small:

• Avoid large dependencies
• Use tree-shaking (Vite does this automatically)
• Lazy-load heavy modules

CPU Time Limits

• Free Plan: 10ms CPU time per request
• Paid Plan: 50ms CPU time per request

Tip: Use asynchronous operations (KV, D1, R2) to avoid blocking CPU time.

Memory Limits

• 128 MB per Worker instance

Tip: Avoid loading large files into memory. Stream data when possible.

Request Size Limits

• Request Body: 100 MB
• Response Body: No limit (can stream)

---

Best Practices

1. Use Middleware for Common Logic

import { logger } from 'hono/logger'
import { cors } from 'hono/cors'

app.use('*', logger())
app.use('/api/*', cors())

2. Separate API and Static Routes

const api = new Hono()

api.get('/users', ...)
api.get('/posts', ...)

app.route('/api', api)
app.all('*', (c) => c.env.ASSETS.fetch(c.req.raw))

3. Handle Errors Gracefully

app.onError((err, c) => {
  console.error(err)
  return c.json({ error: 'Internal Server Error' }, 500)
})

4. Use TypeScript

// Define types for request/response
type User = {
  id: number
  name: string
}

app.get('/api/users/:id', async (c) => {
  const id = parseInt(c.req.param('id'))
  const user: User = { id, name: 'Alice' }
  return c.json(user)
})

5. Validate Input

import { z } from 'zod'

const schema = z.object({
  name: z.string(),
  email: z.string().email(),
})

app.post('/api/users', async (c) => {
  const body = await c.req.json()
  const validated = schema.parse(body)
  return c.json({ success: true, data: validated })
})

---

Troubleshooting

Issue: API routes return HTML

Cause: Missing run_worker_first configuration

Fix: Add to wrangler.jsonc:

{
  "assets": {
    "run_worker_first": ["/api/*"]
  }
}

Issue: HMR crashes with "A hanging Promise was canceled"

Cause: Race condition in older Vite plugin versions

Fix: Update to latest:

npm install -D @cloudflare/vite-plugin@1.13.13

Issue: Deployment fails with "Cannot read properties of undefined"

Cause: Incorrect export pattern

Fix: Use export default app (not { fetch: app.fetch })

---

For more troubleshooting, see common-issues.md.