Cloudflare Opennext

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

npm create cloudflare@latest -- my-next-app --framework=next --platform=workers
cd my-next-app
npm run dev      # Local development with Next.js
npm run preview  # Preview in Workers runtime
npm run deploy   # Deploy to Cloudflare

Existing App Migration

# 1. Install dependencies
npm install @opennextjs/cloudflare@latest
npm install --save-dev wrangler@latest

# 2. Create wrangler.jsonc (see Configuration section)
# 3. Create open-next.config.ts
# 4. Update next.config.ts
# 5. Add scripts to package.json
# 6. Deploy
npm run deploy

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:

// ❌ Remove this - Edge runtime not supported
export const runtime = "edge";

// ✅ Default Node.js runtime - fully supported
// No export needed, this is the default

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:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-nextjs-app",
  "main": ".open-next/worker.js",
  "compatibility_date": "2024-12-30",
  "compatibility_flags": [
    "nodejs_compat",                    // Required for Node.js APIs
    "global_fetch_strictly_public"      // Security: prevent local IP fetches
  ],
  "assets": {
    "directory": ".open-next/assets",   // Static files
    "binding": "ASSETS"
  },
  "services": [
    {
      "binding": "WORKER_SELF_REFERENCE",
      "service": "my-nextjs-app"        // Must match "name" above
    }
  ],
  "images": {
    "binding": "IMAGES"                 // Optional: Enable image optimization
  }
}

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 for complete configuration with R2, KV, D1 bindings.

open-next.config.ts

Configure caching and OpenNext behavior:

import { defineCloudflareConfig } from "@opennextjs/cloudflare";
import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";

export default defineCloudflareConfig({
  incrementalCache: r2IncrementalCache,
});

This file is auto-generated if not present. See references/caching.md for cache options.

next.config.ts

Initialize OpenNext for local development:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Your Next.js configuration
};

export default nextConfig;

// Enable bindings access during `next dev`
import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
initOpenNextCloudflareForDev();

.dev.vars

Environment variables for local development:

# .dev.vars
NEXTJS_ENV=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:

import { getCloudflareContext } from "@opennextjs/cloudflare";

// Route Handler (App Router)
export async function GET(request: Request) {
  const { env, cf, ctx } = getCloudflareContext();
  
  // Access KV
  const value = await env.MY_KV.get("key");
  
  // Access R2
  const object = await env.MY_BUCKET.get("file.txt");
  
  // Access D1
  const result = await env.DB.prepare("SELECT * FROM users").all();
  
  // Access Durable Objects
  const stub = env.MY_DO.idFromName("instance-1");
  const doResponse = await stub.fetch(request);
  
  // Access request info
  const country = cf?.country;
  
  // Background tasks
  ctx.waitUntil(logAnalytics());
  
  return Response.json({ value });
}

// API Route (Pages Router)
export default async function handler(req, res) {
  const { env } = getCloudflareContext();
  const data = await env.MY_KV.get("key");
  res.json({ data });
}

// Server Component
export default async function Page() {
  const { env } = getCloudflareContext();
  const data = await env.MY_KV.get("key");
  return <div>{data}</div>;
}

SSG Routes with Async Context

For Static Site Generation routes, use async mode:

// In SSG route (generateStaticParams, etc.)
const { env } = await getCloudflareContext({ async: true });
const products = await env.DB.prepare("SELECT * FROM products").all();

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:

npx wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts

Add to package.json:

{
  "scripts": {
    "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
  }
}

Run after any binding changes in wrangler.jsonc.

CLI Commands

The opennextjs-cloudflare CLI wraps Wrangler with OpenNext-specific behavior:

# Build the Next.js app and transform for Workers
npx opennextjs-cloudflare build

# Build and preview locally with Wrangler
npm run preview
# or
npx opennextjs-cloudflare preview

# Build and deploy to Cloudflare
npm run deploy
# or
npx opennextjs-cloudflare deploy

# Build and upload as a version (doesn't deploy)
npm run upload
# or
npx opennextjs-cloudflare upload

# Populate cache (called automatically by preview/deploy/upload)
npx opennextjs-cloudflare populateCache local   # Local bindings
npx opennextjs-cloudflare populateCache remote  # Remote bindings

Recommended package.json scripts:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
    "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
    "upload": "opennextjs-cloudflare build && opennextjs-cloudflare upload",
    "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
  }
}

Caching Strategies

OpenNext supports Next.js caching with Cloudflare storage:

Quick setup examples:

// Static Site (SSG only)
import staticAssetsCache from "@opennextjs/cloudflare/overrides/incremental-cache/static-assets-incremental-cache";
export default defineCloudflareConfig({
  incrementalCache: staticAssetsCache,
  enableCacheInterception: true,
});

// Small Site with ISR