jackspace/claudeskillz/cloudflare-nextjs

Cloudflare Next.js Deployment Skill

Deploy Next.js applications to Cloudflare Workers using the OpenNext Cloudflare adapter for production-ready serverless Next.js hosting.

Use This Skill When

• Deploying Next.js applications (App Router or Pages Router) to Cloudflare Workers
• Need server-side rendering (SSR), static site generation (SSG), or incremental static regeneration (ISR) on Cloudflare
• Migrating existing Next.js apps from Vercel, AWS, or other platforms to Cloudflare
• Building full-stack Next.js applications with Cloudflare services (D1, R2, KV, Workers AI)
• Need React Server Components, Server Actions, or Next.js middleware on Workers
• Want global edge deployment with Cloudflare's network

Key Concepts

OpenNext Adapter Architecture

The OpenNext Cloudflare adapter (@opennextjs/cloudflare) transforms Next.js build output into Cloudflare Worker-compatible format. This is fundamentally different from standard Next.js deployments:

• Node.js Runtime Required: Uses Node.js runtime in Workers (NOT Edge runtime)
• Dual Development Workflow: Test in both Next.js dev server AND workerd runtime
• Custom Build Pipeline: next build → OpenNext transformation → Worker deployment
• Cloudflare-Specific Configuration: Requires wrangler.jsonc and open-next.config.ts

Critical Differences from Standard Next.js

Setup Patterns

New Project Setup

Use Cloudflare's create-cloudflare (C3) CLI to scaffold a new Next.js project pre-configured for Workers:

npm create cloudflare@latest -- my-next-app --framework=next

What this does:

1. Runs Next.js official setup tool (create-next-app)
2. Installs @opennextjs/cloudflare adapter
3. Creates wrangler.jsonc with correct configuration
4. Creates open-next.config.ts for caching configuration
5. Adds deployment scripts to package.json
6. Optionally deploys immediately to Cloudflare

Development workflow:

npm run dev      # Next.js dev server (fast reloads)
npm run preview  # Test in workerd runtime (production-like)
npm run deploy   # Build and deploy to Cloudflare

Existing Project Migration

To add the OpenNext adapter to an existing Next.js application:

1. Install the adapter

npm install --save-dev @opennextjs/cloudflare

2. Create wrangler.jsonc

{
  "name": "my-next-app",
  "compatibility_date": "2025-05-05",
  "compatibility_flags": ["nodejs_compat"]
}

Critical configuration:

• compatibility_date: Minimum `2025-05-05` (for FinalizationRegistry support)
• compatibility_flags: Must include `nodejs_compat` (for Node.js runtime)

3. Create open-next.config.ts

import { defineCloudflareConfig } from "@opennextjs/cloudflare";
export default defineCloudflareConfig({
  // Caching configuration (optional)
  // See: https://opennext.js.org/cloudflare/caching
});

4. Update package.json scripts

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
    "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
    "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
  }
}

Script purposes:

• dev: Next.js development server (fast iteration)
• preview: Build + run in workerd runtime (test before deploy)
• deploy: Build + deploy to Cloudflare
• cf-typegen: Generate TypeScript types for Cloudflare bindings

5. Ensure Node.js runtime (not Edge)

Remove Edge runtime exports from your app:

// ❌ REMOVE THIS (Edge runtime not supported)
export const runtime = "edge";
// ✅ Use Node.js runtime (default)
// No export needed - Node.js is default

Development Workflow

Dual Testing Strategy

Always test in BOTH environments:

1. Next.js Dev Server (npm run dev)

• Fast hot reloading
• Best developer experience
• Runs in Node.js (not production runtime)
• Use for rapid iteration

1. Workerd Runtime (npm run preview)

• Runs in production-like environment
• Catches runtime-specific issues
• Slower rebuild times
• Required before deployment

When to Use Each

# Iterating on UI/logic → Use Next.js dev server
npm run dev
 
# Testing integrations (D1, R2, KV) → Use preview
npm run preview
 
# Before deploying → ALWAYS test preview
npm run preview
 
# Deploy to production
npm run deploy

Configuration Requirements

Wrangler Configuration

Minimum requirements in wrangler.jsonc:

{
  "name": "your-app-name",
  "compatibility_date": "2025-05-05",  // Minimum for FinalizationRegistry
  "compatibility_flags": ["nodejs_compat"]  // Required for Node.js runtime
}

Environment Variables for Package Exports

If using npm packages with multiple export conditions, create .env:

WRANGLER_BUILD_CONDITIONS=""
WRANGLER_BUILD_PLATFORM="node"

This ensures Wrangler prioritizes the node export when available.

Cloudflare Bindings Integration

Add bindings in wrangler.jsonc:

{
  "name": "your-app-name",
  "compatibility_date": "2025-05-05",
  "compatibility_flags": ["nodejs_compat"],
 
  // D1 Database
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "production-db",
      "database_id": "your-database-id"
    }
  ],
 
  // R2 Storage
  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "your-bucket"
    }
  ],
 
  // KV Storage
  "kv_namespaces": [
    {
      "binding": "KV",
      "id": "your-kv-id"
    }
  ],
 
  // Workers AI
  "ai": {
    "binding": "AI"
  }
}

Access bindings in Next.js via process.env:

// app/api/route.ts
import type { NextRequest } from 'next/server';
export async function GET(request: NextRequest) {
  // Access Cloudflare bindings
  const env = process.env as any;
  // D1 Database query
  const result = await env.DB.prepare('SELECT * FROM users').all();
  // R2 Storage access
  const file = await env.BUCKET.get('file.txt');
  // KV Storage access
  const value = await env.KV.get('key');
  // Workers AI inference
  const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
    prompt: 'Hello AI'
  });
  return Response.json({ result });
}

Error Prevention (10+ Documented Errors)

1. Worker Size Limit Exceeded (3 MiB - Free Plan)

Error: "Your Worker exceeded the size limit of 3 MiB"

Cause: Workers Free plan limits Worker size to 3 MiB (gzip-compressed)

Solutions:

• Upgrade to Workers Paid plan (10 MiB limit)
• Analyze bundle size and remove unused dependencies
• Use dynamic imports to code-split large dependencies

Bundle analysis:

npx opennextjs-cloudflare build
cd .open-next/server-functions/default
# Analyze handler.mjs.meta.json with ESBuild Bundle Analyzer

Source: https://opennext.js.org/cloudflare/troubleshooting#worker-size-limits

2. Worker Size Limit Exceeded (10 MiB - Paid Plan)

Error: "Your Worker exceeded the size limit of 10 MiB"

Cause: Unnecessary code bundled into Worker

Debug workflow:

1. Run npx opennextjs-cloudflare build
2. Navigate to .open-next/server-functions/default
3. Analyze handler.mjs.meta.json using ESBuild Bundle Analyzer
4. Identify and remove/externalize large dependencies

Source: https://opennext.js.org/cloudflare/troubleshooting#worker-size-limits

3. FinalizationRegistry Not Defined

Error: "ReferenceError: FinalizationRegistry is not defined"

Cause: compatibility_date in wrangler.jsonc is too old

Solution: Update compatibility_date to 2025-05-05 or later:

{
  "compatibility_date": "2025-05-05"  // Minimum for FinalizationRegistry
}

Source: https://opennext.js.org/cloudflare/troubleshooting#finalizationregistry-is-not-defined

4. Cannot Perform I/O on Behalf of Different Request

Error: "Cannot perform I/O on behalf of a different request"

Cause: Database client created globally and reused across requests

Problem code:

// ❌ WRONG: Global DB client
import { Pool } from 'pg';
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
export async function GET() {
  // This will fail - pool created in different request context
  const result = await pool.query('SELECT * FROM users');
  return Response.json(result);
}

Solution: Create database clients inside request handlers:

// ✅ CORRECT: Request-scoped DB client
import { Pool } from 'pg';
export async function GET() {
  // Create client within request context
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const result = await pool.query('SELECT * FROM users');
  await pool.end();
  return Response.json(result);
}

Alternative: Use Cloudflare D1 (designed for Workers) instead of external databases:

// ✅ BEST: Use D1 (no connection pooling needed)
export async function GET(request: NextRequest) {
  const env = process.env as any;
  const result = await env.DB.prepare('SELECT * FROM users').all();
  return Response.json(result);
}

Source: https://opennext.js.org/cloudflare/troubleshooting#cannot-perform-io-on-behalf-of-a-different-request

5. NPM Package Import Failures

Error: "Could not resolve '<package>'"

Cause: Missing nodejs_compat flag or package export conditions

Solution 1: Enable nodejs_compat flag:

{
  "compatibility_flags": ["nodejs_compat"]
}

Solution 2: For packages with multiple exports, create .env:

WRANGLER_BUILD_CONDITIONS=""
WRANGLER_BUILD_PLATFORM="node"

Source: https://opennext.js.org/cloudflare/troubleshooting#npm-packages-fail-to-import

6. Failed to Load Chunk (Turbopack)

Error: "Failed to load chunk server/chunks/ssr/"

Cause: Next.js built with Turbopack (next build --turbo)

Solution: Use standard build (Turbopack not supported by adapter):

{
  "scripts": {
    "build": "next build"  // ✅ Correct
    // "build": "next build --turbo"  // ❌ Don't use Turbopack
  }
}

Source: https://opennext.js.org/cloudflare/troubleshooting#failed-to-load-chunk

7. SSRF Vulnerability (CVE-2025-6087)

Vulnerability: Server-Side Request Forgery via /_next/image endpoint

Affected versions: @opennextjs/cloudflare < 1.3.0

Solution: Upgrade to version 1.3.0 or later:

npm install --save-dev @opennextjs/cloudflare@^1.3.0

Impact: Allows unauthenticated users to proxy arbitrary remote content

Source: https://github.com/advisories/GHSA-rvpw-p7vw-wj3m

8. Durable Objects Binding Warnings

Warning: "You have defined bindings to the following internal Durable Objects... will not work in local development, but they should work in production"

Cause: OpenNext uses Durable Objects for caching (DOQueueHandler, DOShardedTagCache)

Solution: Safe to ignore - warning is expected behavior

Alternative (to suppress warning): Define Durable Objects in separate Worker with own config

Source: https://opennext.js.org/cloudflare/known-issues#caching-durable-objects

9. Prisma + D1 Middleware Conflicts

Error: Build errors when using @prisma/client + @prisma/adapter-d1 in Next.js middleware