Deploy Next.js applications to Cloudflare Workers using the OpenNext Cloudflare adapter for production-ready serverless Next.js hosting.
/plugin marketplace add secondsky/claude-skills/plugin install cloudflare-nextjs@claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
assets/workflow-diagram.mdreferences/database-client-example.tsreferences/error-catalog-extended.mdreferences/feature-support.mdreferences/open-next.config.tsreferences/package.jsonreferences/service-integration-patterns.mdreferences/troubleshooting.mdreferences/wrangler.jsoncscripts/analyze-bundle.shscripts/setup-existing-project.shscripts/setup-new-project.shDeploy Next.js applications to Cloudflare Workers using the OpenNext Cloudflare adapter for production-ready serverless Next.js hosting.
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.
OpenNext Adapter transforms Next.js builds for Workers. Critical requirements:
nodejs_compat flagnext dev for speed, preview for production-like validationUse 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:
create-next-app)@opennextjs/cloudflare adapterwrangler.jsonc with correct configurationopen-next.config.ts for caching configurationpackage.jsonDevelopment 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
To add the OpenNext adapter to an existing Next.js application:
bun add -d @opennextjs/cloudflare
{
"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)import { defineCloudflareConfig } from "@opennextjs/cloudflare";
export default defineCloudflareConfig({
// Caching configuration (optional)
// See: https://opennext.js.org/cloudflare/caching
});
{
"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 Cloudflarecf-typegen: Generate TypeScript types for Cloudflare bindingsRemove 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
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 deployCritical: Always test preview before deploying to catch Workers-specific runtime issues
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
These are the most common deployment-blocking errors. For the complete catalog of 11+ errors, load references/error-catalog-extended.md.
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
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();
}
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
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
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 | 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 |
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:
npm run cf-typegen)Related Skills: cloudflare-d1, cloudflare-r2, cloudflare-kv, cloudflare-workers-ai for service-specific deep dives
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
Node.js Middleware (Next.js 15.2+)
Edge Runtime
export const runtime = "edge" from your appFull Windows Support
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 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
npm run previewnpm run deploySame process as Vercel migration - the adapter handles Next.js standard features automatically.
cloudflare-worker-base - Base Worker setup with Hono + Vite + Reactcloudflare-d1 - D1 database integrationcloudflare-r2 - R2 object storagecloudflare-kv - KV key-value storagecloudflare-workers-ai - Workers AI integrationcloudflare-vectorize - Vector database for RAG# 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
// wrangler.jsonc
{
"compatibility_date": "2025-05-05", // Minimum!
"compatibility_flags": ["nodejs_compat"] // Required!
}
dev → ✅ Always test preview before deployProduction Tested: Official Cloudflare support and active community Token Savings: ~59% vs manual setup Errors Prevented: 11+ documented issues Last Verified: 2025-12-04
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.