cloudflare-nextjs

name	cloudflare-nextjs
description	Deploy Next.js applications (App Router and Pages Router) to Cloudflare Workers using the OpenNext adapter. This skill should be used when deploying Next.js apps with SSR, ISR, or server components to Cloudflare's serverless platform. It covers setup for both new and existing projects, configuration requirements, development workflows, integration with Cloudflare services (D1, R2, KV, Workers AI), and prevention of 10+ documented errors including worker size limits, runtime compatibility, database connection scoping, and security vulnerabilities. Keywords: Cloudflare Next.js, OpenNext Cloudflare, @opennextjs/cloudflare, Next.js Workers, Next.js App Router Cloudflare, Next.js Pages Router Cloudflare, Next.js SSR Cloudflare, Next.js ISR, server components cloudflare, server actions cloudflare, Next.js middleware workers, nextjs d1, nextjs r2, nextjs kv, Next.js deployment, opennextjs-cloudflare cli, nodejs_compat, worker size limit, next.js runtime compatibility, database connection scoping, Next.js migration cloudflare
license	MIT
metadata	{"version":"1.0.0","last_verified":"2025-10-21T00:00:00.000Z","package_versions":{"@opennextjs/cloudflare":"^1.3.0","next":"^14.2.0 || ^15.0.0","wrangler":"latest"},"compatibility_requirements":{"compatibility_date":"2025-05-05","compatibility_flags":["nodejs_compat"]},"token_savings":"~59%","errors_prevented":10,"official_docs":"https://opennext.js.org/cloudflare","cloudflare_guide":"https://developers.cloudflare.com/workers/framework-guides/web-apps/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

Aspect	Standard Next.js	Cloudflare Workers
Runtime	Node.js or Edge	Node.js (via nodejs_compat)
Dev Server	next dev	next dev + opennextjs-cloudflare preview
Deployment	Platform-specific	opennextjs-cloudflare deploy
Worker Size	No limit	3 MiB (free) / 10 MiB (paid)
Database Connections	Global clients OK	Must be request-scoped
Image Optimization	Built-in	Via Cloudflare Images
Caching	Next.js cache	OpenNext config + Workers cache

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

2. 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

Cause: Database initialization in middleware context

Workaround: Initialize Prisma client in route handlers, not middleware

Source: https://github.com/opennextjs/opennextjs-cloudflare/issues/471

---

10. cross-fetch Library Errors

Error: Errors when using libraries that depend on cross-fetch

Cause: OpenNext patches deployment package causing cross-fetch to try using Node.js libraries when native fetch is available

Solution: Use native fetch API directly instead of cross-fetch:

// ✅ Use native fetch
const response = await fetch('https://api.example.com/data');

// ❌ Avoid cross-fetch
// import fetch from 'cross-fetch';

Source: https://opennext.js.org/cloudflare/troubleshooting

---

11. Windows Development Issues

Issue: Full Windows support not guaranteed

Cause: Underlying Next.js tooling issues on Windows

Solutions:

• Use WSL (Windows Subsystem for Linux)
• Use virtual machine with Linux
• Use Linux-based CI/CD for deployments

Source: https://opennext.js.org/cloudflare#windows-support

Feature Support Matrix

Feature	Status	Notes
App Router	✅ Fully Supported	Latest App Router features work
Pages Router	✅ Fully Supported	Legacy Pages Router supported
Route Handlers	✅ Fully Supported	API routes work as expected
React Server Components	✅ Fully Supported	RSC fully functional
Server Actions	✅ Fully Supported	Server Actions work
SSG	✅ Fully Supported	Static Site Generation
SSR	✅ Fully Supported	Server-Side Rendering
ISR	✅ Fully Supported	Incremental Static Regeneration
Middleware	✅ Supported	Except Node.js middleware (15.2+)
Image Optimization	✅ Supported	Via Cloudflare Images
Partial Prerendering (PPR)	✅ Supported	Experimental in Next.js
Composable Caching	✅ Supported	'use cache' directive
Response Streaming	✅ Supported	Streaming responses work
next/after API	✅ Supported	Post-response async work
Node.js Middleware (15.2+)	❌ Not Supported	Future support planned
Edge Runtime	❌ Not Supported	Use Node.js runtime

Source: https://developers.cloudflare.com/workers/framework-guides/web-apps/nextjs/#next-js-supported-features

Integration with Cloudflare Services

D1 Database (SQL)

// app/api/users/route.ts
import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const env = process.env as any;

  const result = await env.DB.prepare(
    'SELECT * FROM users WHERE active = ?'
  ).bind(true).all();

  return Response.json(result.results);
}

export async function POST(request: NextRequest) {
  const env = process.env as any;
  const { name, email } = await request.json();

  const result = await env.DB.prepare(
    'INSERT INTO users (name, email) VALUES (?, ?)'
  ).bind(name, email).run();

  return Response.json({ id: result.meta.last_row_id });
}

Wrangler config:

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "production-db",
      "database_id": "your-database-id"
    }
  ]
}

See also: cloudflare-d1 skill for complete D1 patterns

---

R2 Storage (Object Storage)

// app/api/upload/route.ts
import type { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const env = process.env as any;
  const formData = await request.formData();
  const file = formData.get('file') as File;

  // Upload to R2
  await env.BUCKET.put(file.name, file.stream(), {
    httpMetadata: {
      contentType: file.type
    }
  });

  return Response.json({ success: true, filename: file.name });
}

export async function GET(request: NextRequest) {
  const env = process.env as any;
  const { searchParams } = new URL(request.url);
  const filename = searchParams.get('file');

  const object = await env.BUCKET.get(filename);
  if (!object) {
    return new Response('Not found', { status: 404 });
  }

  return new Response(object.body, {
    headers: {
      'Content-Type': object.httpMetadata?.contentType || 'application/octet-stream'
    }
  });
}

See also: cloudflare-r2 skill for complete R2 patterns

---

Workers AI (Model Inference)

// app/api/ai/route.ts
import type { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const env = process.env as any;
  const { prompt } = await request.json();

  const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
    prompt
  });

  return Response.json(response);
}

Wrangler config:

{
  "ai": {
    "binding": "AI"
  }
}

See also: cloudflare-workers-ai skill for complete AI patterns

---

KV Storage (Key-Value)

// app/api/cache/route.ts
import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const env = process.env as any;
  const { searchParams } = new URL(request.url);
  const key = searchParams.get('key');

  const value = await env.KV.get(key);
  return Response.json({ key, value });
}

export async function PUT(request: NextRequest) {
  const env = process.env as any;
  const { key, value, ttl } = await request.json();

  await env.KV.put(key, value, { expirationTtl: ttl });
  return Response.json({ success: true });
}

See also: cloudflare-kv skill for complete KV patterns

Image Optimization

Next.js image optimization works via Cloudflare Images. Configure in open-next.config.ts:

import { defineCloudflareConfig } from "@opennextjs/cloudflare";

export default defineCloudflareConfig({
  imageOptimization: {
    loader: 'cloudflare'
  }
});

Usage in components:

import Image from 'next/image';

export default function Avatar() {
  return (
    <Image
      src="/avatar.jpg"
      alt="User avatar"
      width={200}
      height={200}
      // Automatically optimized via Cloudflare Images
    />
  );
}

Billing: Cloudflare Images usage is billed separately

Docs: https://developers.cloudflare.com/images/

Caching Configuration

Configure caching behavior in open-next.config.ts:

import { defineCloudflareConfig } from "@opennextjs/cloudflare";

export default defineCloudflareConfig({
  // Custom cache configuration
  cache: {
    // Override default cache behavior
    // See: https://opennext.js.org/cloudflare/caching
  }
});

Default behavior: OpenNext provides sensible caching defaults

Advanced usage: See official OpenNext caching documentation

Known Limitations

Not Yet Supported

1. Node.js Middleware (Next.js 15.2+)

   • Introduced in Next.js 15.2
   • Support planned for future releases
   • Use standard middleware for now

2. Edge Runtime

   • Only Node.js runtime supported
   • Remove export const runtime = "edge" from your app

3. Full Windows Support

   • Development on Windows not fully guaranteed
   • Use WSL, VM, or Linux-based CI/CD

Worker Size Constraints

• Free plan: 3 MiB limit (gzip-compressed)
• Paid plan: 10 MiB limit (gzip-compressed)
• Monitor bundle size during development
• Use dynamic imports for code splitting

Database Connections

• External database clients (PostgreSQL, MySQL) must be request-scoped
• Cannot reuse connections across requests (Workers limitation)
• Prefer Cloudflare D1 for database needs (designed for Workers)

Deployment

Deploy from Local Machine

# Build and deploy in one command
npm run deploy

# Or step by step:
npx opennextjs-cloudflare build
npx opennextjs-cloudflare deploy

Deploy from CI/CD

Configure deployment command in your CI/CD system:

npm run deploy

Examples:

• GitHub Actions: .github/workflows/deploy.yml
• GitLab CI: .gitlab-ci.yml
• Cloudflare Workers Builds: Auto-detects npm run deploy

Environment variables: Set secrets in Cloudflare dashboard or CI/CD system

Custom Domains

Add custom domain in Cloudflare dashboard:

1. Navigate to Workers & Pages
2. Select your Worker
3. Settings → Domains & Routes
4. Add custom domain

DNS: Domain must be on Cloudflare (zone required)

TypeScript Support

Generate types for Cloudflare bindings:

npm run cf-typegen

Creates cloudflare-env.d.ts with types for your bindings:

// cloudflare-env.d.ts (auto-generated)
interface CloudflareEnv {
  DB: D1Database;
  BUCKET: R2Bucket;
  KV: KVNamespace;
  AI: Ai;
}

Use in route handlers:

import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const env = process.env as CloudflareEnv;
  // Now env.DB, env.BUCKET, etc. are typed
}

Testing

Local Testing (Development)

# Next.js dev server (fast iteration)
npm run dev

Local Testing (Production-like)

# Workerd runtime (catches Workers-specific issues)
npm run preview

Integration Testing

Always test in preview mode before deploying:

# Build and run in workerd
npm run preview

# Test bindings (D1, R2, KV, AI)
# Test middleware
# Test API routes
# Test SSR/ISR behavior

Migration from Other Platforms

From Vercel

1. Copy existing Next.js project
2. Run existing project migration steps (above)
3. Update environment variables in Cloudflare dashboard
4. Replace Vercel-specific features:
   • Vercel Postgres → Cloudflare D1
   • Vercel Blob → Cloudflare R2
   • Vercel KV → Cloudflare KV
   • Vercel Edge Config → Cloudflare KV
5. Test thoroughly with npm run preview
6. Deploy with npm run deploy

From AWS / Other Platforms

Same process as Vercel migration - the adapter handles Next.js standard features automatically.

Resources

Official Documentation

• OpenNext Cloudflare: https://opennext.js.org/cloudflare
• Cloudflare Next.js Guide: https://developers.cloudflare.com/workers/framework-guides/web-apps/nextjs/
• Next.js Docs: https://nextjs.org/docs

Troubleshooting

• Troubleshooting Guide: https://opennext.js.org/cloudflare/troubleshooting
• Known Issues: https://opennext.js.org/cloudflare/known-issues
• GitHub Issues: https://github.com/opennextjs/opennextjs-cloudflare/issues

Related Skills

• cloudflare-worker-base - Base Worker setup with Hono + Vite + React
• cloudflare-d1 - D1 database integration
• cloudflare-r2 - R2 object storage
• cloudflare-kv - KV key-value storage
• cloudflare-workers-ai - Workers AI integration
• cloudflare-vectorize - Vector database for RAG

Quick Reference

Essential Commands

# New project
npm create cloudflare@latest -- my-next-app --framework=next

# Development
npm run dev      # Fast iteration (Next.js dev server)
npm run preview  # Test in workerd (production-like)

# Deployment
npm run deploy   # Build and deploy to Cloudflare

# TypeScript
npm run cf-typegen  # Generate binding types

Critical Configuration

// wrangler.jsonc
{
  "compatibility_date": "2025-05-05",  // Minimum!
  "compatibility_flags": ["nodejs_compat"]  // Required!
}

Common Pitfalls

1. ❌ Using Edge runtime → ✅ Use Node.js runtime
2. ❌ Global DB clients → ✅ Request-scoped clients
3. ❌ Old compatibility_date → ✅ Use 2025-05-05+
4. ❌ Missing nodejs_compat → ✅ Add to compatibility_flags
5. ❌ Only testing in dev → ✅ Always test preview before deploy
6. ❌ Using Turbopack → ✅ Use standard Next.js build

---

Production Tested: Official Cloudflare support and active community Token Savings: ~59% vs manual setup Errors Prevented: 10+ documented issues Last Verified: 2025-10-21