cloudflare-workers-frameworks

Workers Frameworks Integration

Build full-stack applications on Cloudflare Workers using modern frameworks.

Quick Start: Choose Your Framework

Framework	Best For	SSR	Static	Workers Native
Hono	APIs, lightweight apps	✅	✅	✅ Native
Remix	Full-stack apps	✅	✅	✅ Adapter
Next.js	React apps	✅	✅	⚠️ OpenNext
Astro	Content sites	✅	✅	✅ Adapter
SvelteKit	Svelte apps	✅	✅	✅ Adapter
Qwik	Resumable apps	✅	✅	✅ Adapter
Nuxt	Vue apps	✅	✅	✅ Nitro

Framework Decision Tree

Need an API only?
  └─ Yes → Hono (fastest, smallest)
  └─ No → Building a full app?
           └─ React → Next.js (OpenNext) or Remix
           └─ Vue → Nuxt
           └─ Svelte → SvelteKit
           └─ Content-heavy → Astro
           └─ Max performance → Qwik

Top 10 Framework Errors

Error	Framework	Cause	Solution
No matching export "default"	All	Wrong export format	Use export default app not module.exports
Worker exceeded CPU limit	Next.js	Heavy SSR	Use ISR, reduce bundle size
Cannot read properties of undefined (reading 'env')	Remix	Missing context	Pass context to loader/action
globalThis is not defined	All	Node.js globals	Use nodejs_compat flag
Dynamic require not supported	All	CJS in ESM	Convert to ESM imports
Response body is locked	All	Body already read	Clone response before reading
Bindings not available	All	Missing wrangler config	Add bindings to wrangler.jsonc
404 on static assets	All	Wrong assets config	Configure assets in wrangler.jsonc
Hydration mismatch	React/Vue	Server/client differ	Ensure consistent rendering
Maximum call stack exceeded	All	Circular imports	Refactor module structure

Hono Quick Start (Recommended)

// src/index.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { logger } from 'hono/logger';

interface Env {
  DB: D1Database;
  KV: KVNamespace;
}

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

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

// Routes
app.get('/', (c) => c.text('Hello Workers!'));

app.get('/api/users', async (c) => {
  const { results } = await c.env.DB.prepare('SELECT * FROM users').all();
  return c.json(results);
});

app.post('/api/users', async (c) => {
  const { name, email } = await c.req.json();
  await c.env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
    .bind(name, email)
    .run();
  return c.json({ success: true }, 201);
});

export default app;

// wrangler.jsonc
{
  "name": "my-app",
  "main": "src/index.ts",
  "compatibility_date": "2024-12-01",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "xxx" }
  ]
}

Static Assets Configuration

// wrangler.jsonc - Serving static files
{
  "name": "my-app",
  "main": "src/index.ts",
  "assets": {
    "directory": "./public",
    "binding": "ASSETS"
  }
}

// Serve static with fallback to app
import { Hono } from 'hono';

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

// API routes
app.get('/api/*', apiHandler);

// Static assets fallback
app.get('*', async (c) => {
  return c.env.ASSETS.fetch(c.req.raw);
});

export default app;

When to Load References

Load the specific framework reference when user:

Reference	Load When
references/hono.md	Building APIs, microservices, or lightweight apps
references/remix.md	Full-stack React with loaders/actions
references/nextjs.md	Next.js App Router on Workers via OpenNext
references/astro.md	Content sites, blogs, docs, marketing pages
references/sveltekit.md	Svelte applications on Workers
references/qwik.md	Resumable apps, instant loading
references/nuxt.md	Vue 3 applications with Nitro

Common Patterns Across Frameworks

Environment Bindings Access

// Hono
app.get('/', (c) => c.env.DB.prepare('...'));

// Remix
export async function loader({ context }) {
  return context.cloudflare.env.DB.prepare('...');
}

// Astro
const db = Astro.locals.runtime.env.DB;

// SvelteKit
export async function load({ platform }) {
  return platform.env.DB.prepare('...');
}

// Nuxt
const { cloudflare } = useRuntimeConfig();
// Or via nitro: event.context.cloudflare.env.DB

Error Handling Pattern

// Universal error boundary pattern
app.onError((err, c) => {
  console.error(`[${c.req.path}] ${err.message}`);

  if (err instanceof HTTPException) {
    return err.getResponse();
  }

  return c.json(
    { error: 'Internal Server Error' },
    500
  );
});

Performance Tips

1. Bundle Size: Keep under 1MB compressed
2. Cold Starts: Minimize top-level code
3. Streaming: Use streaming SSR when available
4. Caching: Leverage Cache API and CDN
5. Code Splitting: Dynamic imports for routes

See Also

• workers-performance - Optimization techniques
• workers-runtime-apis - Workers APIs reference
• cloudflare-worker-base - Basic Workers setup