Deploy Next.js to Cloudflare Workers with full App Router, Pages Router, ISR, and SSG support. Load when creating Next.js projects for Workers, migrating from Vercel/next-on-pages, configuring caching (R2/KV/D1), accessing Cloudflare bindings via getCloudflareContext, or fixing bundle size issues.

Cloudflare OpenNext Deploy Next.js applications to Cloudflare Workers using the @opennextjs/cloudflare adapter with full support for App Router, Pages Router, ISR, SSG, and Cloudflare bindings. When to Use Creating new Next.js apps for Cloudflare Workers Migrating existing Next.js apps to Cloudflare Configuring ISR/SSG caching with R2, KV, or D1 Accessing Cloudflare bindings (KV, R2, D1, Durable Objects, AI) Using databases and ORMs (Drizzle, Prisma) in Next.js Troubleshooting deployment issues or bundle size problems Getting Started New App Existing App Migration Core Concepts How OpenNext Works The @opennextjs/cloudflare adapter: 1. Runs next build to generate the Next.js build output 2. Transforms the build output to work in Cloudflare Workers runtime 3. Outputs to .open next/ directory with worker.js entry point 4. Uses Workers Static Assets for static files ( next/static , public ) Node.js Runtime (Not Edge) Critical : OpenNext uses Next.js Node.js runtime , NOT the Edge runtime: The Node.js runtime provides: Full Node.js API compatibility via nodejs compat flag More Next.js features than Edge runtime Access to all Cloudflare bindings Configuration Files wrangler.jsonc Minimal configuration for OpenNext: Required settings : nodejs compat compatibility flag compatibility date = 2024 09 23 WORKER SELF REFERENCE service binding (must match worker name) main and assets paths should not be changed See [references/configuration.md](references/configuration.md) for complete configuration with R2, KV, D1 bindings. open next.config.ts Configure caching and OpenNext behavior: This file is auto generated if not present. See [references/caching.md](references/caching.md) for cache options. next.config.ts Initialize OpenNext for local development: .dev.vars Environment variables for local development: The NEXTJS ENV variable selects which Next.js .env file to load: development → .env.development production → .env.production (default) Accessing Cloudflare Bindings Use getCloudflareContext() to access bindings in any route: SSG Routes with Async Context For Static Site Generation routes, use async mode: Warning : During SSG, secrets from .dev.vars and local binding values are included in the static build. Be careful with sensitive data. TypeScript Types Generate types for your bindings: Add to package.json : Run after any binding changes in wrangler.jsonc . CLI Commands The opennextjs cloudflare CLI wraps Wrangler with OpenNext specific behavior: Recommended package.json scripts : Caching Strategies OpenNext supports Next.js caching with Cloudflare storage: Cache Type Use Case Storage Options Incremental Cache ISR/SSG page data R2, KV, Static Assets Queue Time based revalidation Durable Objects, Memory Tag Cache On demand revalidation D1, Durable Objects Quick setup examples: See [references/caching.md](references/caching.md) for complete caching patterns including regional cache and sharded tag cache Image Optimization Enable Cloudflare Images for automatic image optimization: Next.js <Image components will automatically use Cloudflare Images. Additional costs apply. Compatibility notes : Supports: PNG, JPEG, WEBP, AVIF, GIF, SVG minimumCacheTTL not supported dangerouslyAllowLocalIP not supported Database and ORM Patterns Critical Rule : Never create global database clients in Workers. Create per request: See [references/database orm.md](references/database orm.md) for Drizzle and Prisma patterns. Critical Rules ✅ DO 1. Use Node.js runtime Default runtime, remove any export const runtime = "edge" 2. Create DB clients per request Use React's cache() for request scoped instances 3. Enable nodejs compat Required compatibility flag with date = 2024 09 23 4. Use getCloudflareContext() Access bindings, not getRequestContext from next on pages 5. Add .open next to .gitignore Build output should not be committed 6. Use wrangler.jsonc Not wrangler.toml (JSONC supports comments and validation) 7. Set WORKER SELF REFERENCE Service binding must match worker name 8. Add public/ headers Configure static asset caching headers ❌ DON'T 1. Don't use Edge runtime Remove export const runtime = "edge" from all routes 2. Don't use Turbopack Use next build , not next build turbo 3. Don't create global DB clients Causes "Cannot perform I/O" errors 4. Don't exceed 10 MiB Worker size limit (3 MiB on free plan) 5. Don't use next on pages Different adapter, use @opennextjs/cloudflare instead 6. Don't commit .open next/ Build output directory 7. Don't use Node Middleware Not supported (Next.js 15.2+ feature) Supported Features Feature Support Notes App Router ✅ Full All features supported Pages Router ✅ Full Including API routes Route Handlers ✅ Full GET, POST, etc. Dynamic Routes ✅ Full [slug] , [...slug] SSG ✅ Full Static Site Generation SSR ✅ Full Server Side Rendering ISR ✅ Full Incremental Static Regeneration PPR ✅ Full Partial Prerendering Middleware ✅ Partial Standard middleware works, Node Middleware (15.2+) not supported Image Optimization ✅ Full Via Cloudflare Images binding Composable Caching ✅ Full 'use cache' directive next/font ✅ Full Font optimization after() ✅ Full Background tasks Turbopack ❌ No Use standard build Supported Next.js versions : Next.js 15: All minor and patch versions Next.js 14: Latest minor version only Development Workflow Local Development Notes : next dev Uses Node.js runtime, bindings available via initOpenNextCloudflareForDev() npm run preview Uses Workers runtime with Wrangler, closer to production Both support hot reloading Detailed References [references/configuration.md](references/configuration.md) Complete wrangler.jsonc, environment variables, TypeScript types [references/caching.md](references/caching.md) ISR, SSG, R2/KV/D1 caches, tag cache, queues, cache purge [references/database orm.md](references/database orm.md) Drizzle, Prisma setup with D1, PostgreSQL, Hyperdrive [references/troubleshooting.md](references/troubleshooting.md) Size limits, bundle analysis, common errors Migration from @cloudflare/next on pages If migrating from @cloudflare/next on pages : 1. Uninstall @cloudflare/next on pages and eslint plugin next on pages 2. Install @opennextjs/cloudflare 3. Update next.config.ts : Remove setupDevPlatform() calls Replace with initOpenNextCloudflareForDev() 4. Update imports: Replace getRequestContext from @cloudflare/next on pages Use getCloudflareContext from @opennextjs/cloudflare 5. Remove Edge runtime exports ( export const runtime = "edge" ) 6. Update wrangler.jsonc with required OpenNext settings 7. Remove next on pages eslint rules Examples Official examples in the [@opennextjs/cloudflare repository](https://github.com/opennextjs/opennextjs cloudflare/tree/main/examples): create next app Basic Next.js starter middleware Middleware usage vercel blog starter SSG blog example Best Practices 1. Start simple Use Static Assets cache for SSG only sites 2. Add caching gradually Enable R2 cache when you need ISR 3. Monitor bundle size Stay under 10 MiB compressed (use ESBuild Bundle Analyzer) 4. Use TypeScript Run cf typegen to get binding types 5. Test with preview Use npm run preview before deploying 6. Cache database clients Use React's cache() for per request instances 7. Enable observability Add observability to wrangler.jsonc for logging 8. Use remote bindings for build Enable for ISR with real data Common Patterns See [references/configuration.md](references/configuration.md) for complete examples including: Custom Worker with multiple handlers (fetch, scheduled, queue) Environment specific configuration (staging, production) Remote bindings for build time data access Resources [OpenNext Cloudflare Documentation](https://opennext.js.org/cloudflare) [Next.js Documentation](https://nextjs.org/docs) [Cloudflare Workers Documentation](https://developers.cloudflare.com/workers) [GitHub Repository](https://github.com/opennextjs/opennextjs cloudflare)

cloudflare-opennext