Cloudflare Next.js Deployment Skill

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

When to Load References

Load additional reference files based on your specific task:

• references/error-catalog-extended.md

  - Load when encountering ANY error during setup, build, or deployment. Contains complete catalog of 11+ documented issues with root causes, solutions, and official sources.

• references/service-integration-patterns.md

  - Load when integrating Cloudflare services (D1, R2, KV, Workers AI) with Next.js. Contains complete patterns for database queries, file uploads, caching, and AI inference.

• references/troubleshooting.md

  - Load for general troubleshooting and debugging guidance beyond the error catalog.

• references/feature-support.md

  - Load when checking if a specific Next.js feature is supported on Cloudflare Workers (e.g., "Can I use Server Actions?", "Does ISR work?").

• references/database-client-example.ts

  - Load when integrating external database clients (Drizzle, Prisma, PostgreSQL, MySQL) with proper request-scoping patterns required by Workers.

• references/open-next.config.ts

  - Load when configuring caching behavior, image optimization, or custom OpenNext settings.

• references/package.json

  - Load when setting up a new project or migrating an existing Next.js application to Cloudflare Workers.

• references/wrangler.jsonc

  - Load when configuring Worker settings, compatibility flags, environment bindings (D1, R2, KV, AI), or deployment options.

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 Differences from Standard Next.js

OpenNext Adapter transforms Next.js builds for Workers. Critical requirements:

• Node.js runtime (NOT Edge) via

  nodejs_compat

  flag
• Request-scoped database clients (global clients fail)
• Worker size limits: 3 MiB (free) / 10 MiB (paid)
• Dual testing:

  next dev

  for speed,

  preview

  for production-like validation

Setup Patterns

New Project Setup

Use Cloudflare's

create-cloudflare

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

bun add -d @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 Required:

• npm run dev

  - Fast iteration (Next.js dev server)

• npm run preview

  - Production-like testing (workerd runtime, REQUIRED before deploy)

• npm run deploy

  - Build and deploy

Critical: Always test

preview

Critical Configuration

wrangler.jsonc minimum requirements:

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

Cloudflare Bindings: Add D1, R2, KV, or AI bindings in

wrangler.jsonc

process.env

Package Exports (if needed): Create

.env

WRANGLER_BUILD_PLATFORM="node"

Top 5 Critical Errors

These are the most common deployment-blocking errors. For the complete catalog of 11+ errors, load

references/error-catalog-extended.md

1. Worker Size Limit Exceeded

Error:

"Your Worker exceeded the size limit of 3 MiB"

"10 MiB"

Quick Fix: Upgrade plan, analyze bundle with

bunx opennextjs-cloudflare build

.open-next/server-functions/default/handler.mjs.meta.json

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

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

Error:

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

Cause: Global database client reused across requests (Workers limitation)

Quick Fix: Create database clients INSIDE request handlers, never globally. Or use Cloudflare D1 which is designed for Workers.

// ❌ WRONG: Global client
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

// ✅ CORRECT: Request-scoped
export async function GET() {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  // ... use pool
  await pool.end();
}

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

3. NPM Package Import Failures

Error:

"Could not resolve '<package>'"

Quick Fix: Enable

nodejs_compat

.env

WRANGLER_BUILD_PLATFORM="node"

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

4. SSRF Vulnerability (CVE-2025-6087)

Vulnerability: Server-Side Request Forgery via

/_next/image

Quick Fix: Upgrade immediately:

bun add -d @opennextjs/cloudflare@^1.3.0

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

5. Failed to Load Chunk (Turbopack)

Error:

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

Quick Fix: Remove

--turbo

next build

next build --turbo

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

More Errors: Load

references/error-catalog-extended.md

Feature Support Matrix

'use cache'

next/after

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

Cloudflare Services Integration

Access Cloudflare bindings via

process.env

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

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

  // D1 Database
  const users = await env.DB.prepare('SELECT * FROM users').all();

  // R2 Storage
  const file = await env.BUCKET.get('file.txt');

  // KV Storage
  const value = await env.KV.get('key');

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

  return Response.json({ users, file, value, ai });
}

Wrangler Bindings Configuration:

{
  "d1_databases": [{ "binding": "DB", "database_id": "..." }],
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "..." }],
  "kv_namespaces": [{ "binding": "KV", "id": "..." }],
  "ai": { "binding": "AI" }
}

Detailed Integration Patterns: Load

references/service-integration-patterns.md

• D1: Queries, inserts, transactions, batch operations
• R2: Upload, download, list, delete with streaming
• KV: Get, set with TTL, delete, list keys
• Workers AI: Text generation, embeddings, image classification
• Multi-service integration examples
• TypeScript types for bindings (

  npm run cf-typegen

  )

Related Skills:

cloudflare-d1

cloudflare-r2

cloudflare-kv

cloudflare-workers-ai

Image Optimization & Caching

Images: Automatic optimization via Cloudflare Images (billed separately). Configure in

open-next.config.ts

imageOptimization: { loader: 'cloudflare' }

<Image />

Caching: OpenNext provides sensible defaults. Override in

open-next.config.ts

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

Local:

npm run deploy

CI/CD: Use

npm run deploy

Custom Domains: Workers & Pages → Settings → Domains & Routes (domain must be on Cloudflare)

TypeScript & Testing

TypeScript Types: Run

npm run cf-typegen

cloudflare-env.d.ts

Testing: Always test in

preview

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: 11+ documented issues Last Verified: 2025-12-04