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

• 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

next dev

next dev

opennextjs-cloudflare preview

opennextjs-cloudflare deploy

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

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

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

Solution: Update

compatibility_date

2025-05-05

{
  "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

Solution 1: Enable

nodejs_compat

{
  "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

Affected versions:

@opennextjs/cloudflare

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

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

Solution: Use native

fetch

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

'use cache'

next/after

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

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

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

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

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

// 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

# 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