Cloudflare Nextjs Skill for Claude

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 (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:

• Runs Next.js official setup tool (create-next-app)
• Installs @opennextjs/cloudflare adapter
• Creates wrangler.jsonc with correct configuration
• Creates open-next.config.ts for caching configuration
• Adds deployment scripts to package.json
• 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

Secure Installation

Adapter packages handle production traffic — pin exact versions and audit before upgrading. Follow supply chain security best practices:

• Block post-install scripts — npm config set ignore-scripts true (or Bun: disabled by default)
• Cooldown period — Wait 7 days for new package versions to be vetted by the community
• Audit before installing — Run socket package score npm <pkg> or use socket npm install <pkg> to check packages

Load the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.

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 before deploying to catch Workers-specific runtime issues

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, access via process.env (see "Cloudflare Services Integration" section for complete patterns)

Package Exports (if needed): Create .env with WRANGLER_BUILD_PLATFORM="node" to prioritize Node.js exports

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" (Free) or "10 MiB" (Paid)

Quick Fix: Upgrade plan, analyze bundle with bunx opennextjs-cloudflare build → check .open-next/server-functions/default/handler.mjs.meta.json, remove unused dependencies, or use dynamic imports.

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 flag in wrangler.jsonc, and/or create .env with 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 endpoint in versions < 1.3.0

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 flag from build command. Use next build (standard), NOT next build --turbo.

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

More Errors: Load references/error-catalog-extended.md for 6 additional documented errors including FinalizationRegistry issues, Durable Objects warnings, Prisma conflicts, cross-fetch errors, and Windows development issues

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

Cloudflare Services Integration

Access Cloudflare bindings via process.env in Next.js route handlers:

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 for complete patterns including:

• 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 for service-specific deep dives

Image Optimization & Caching

Images: Automatic optimization via Cloudflare Images (billed separately). Configure in open-next.config.ts with imageOptimization: { loader: 'cloudflare' }. Use standard Next.js <Image /> component.

Caching: OpenNext provides sensible defaults. Override in open-next.config.ts if needed. See https://opennext.js.org/cloudflare/caching for advanced configuration

Known Limitations

Not Yet Supported

• Node.js Middleware (Next.js 15.2+)
• Introduced in Next.js 15.2
• Support planned for future releases
• Use standard middleware for now

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

• 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 (builds and deploys)

CI/CD: Use npm run deploy command in GitHub Actions, GitLab CI, or Cloudflare Workers Builds (auto-detected)

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

TypeScript & Testing

TypeScript Types: Run npm run cf-typegen to generate cloudflare-env.d.ts with typed bindings (D1Database, R2Bucket, KVNamespace, Ai)

Testing: Always test in preview mode before deployment to catch Workers-specific runtime issues and verify bindings work correctly

Migration from Other Platforms

From Vercel

• Copy existing Next.js project
• Run existing project migration steps (above)
• Update environment variables in Cloudflare dashboard
• Replace Vercel-specific features:
• Vercel Postgres → Cloudflare D1
• Vercel Blob → Cloudflare R2
• Vercel KV → Cloudflare KV
• Vercel Edge Config → Cloudflare KV
• Test thoroughly with npm run preview
• 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

• ❌ Using Edge runtime → ✅ Use Node.js runtime
• ❌ Global DB clients → ✅ Request-scoped clients
• ❌ Old compatibility_date → ✅ Use 2025-05-05+
• ❌ Missing nodejs_compat → ✅ Add to compatibility_flags
• ❌ Only testing in dev → ✅ Always test preview before deploy
• ❌ 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