Deploying Next.js App to Cloudflare Workers with OpenNext

If you’ve ever tried deploying a Next.js app to Cloudflare Workers, you’ve probably noticed a gap: Next.js expects Node.js APIs, while Workers traditionally run in a restricted edge runtime.

Enter OpenNext. With the @opennextjs/cloudflare adapter, you can run your Next.js app on Workers using the Node.js runtime, giving you access to many familiar Node APIs — something @cloudflare/next-on-pages can’t provide.

In this guide, we’ll walk through deploying a Next.js app to Cloudflare Workers using OpenNext, step by step.

⚖️ Edge Runtime vs Node.js Runtime

TL;DR: Use Node.js runtime if you need full Next.js features and Node API support; Edge runtime is great for ultra-lightweight functions.

🚀 Let’s Dive In: Creating or Using a Next.js App

Option 1: Start a new Next.js app preconfigured for Workers

If you’re creating a new project, OpenNext can scaffold everything for you:

1npm create cloudflare@latest -- my-next-app --framework=next --platform=workers
Copy

Option 2: Use with an Existing Next.js App

Step 1: Install the Cloudflare Adapter

1npm install -D @opennextjs/cloudflare wrangler
Copy

Step 2: Create wrangler.jsonc (optional)

This file will be auto-generated if not present during build. The nodejs_compat flag enables Node.js APIs in Cloudflare Workers.

1{
2  "$schema": "node_modules/wrangler/config-schema.json",
3  "main": ".open-next/worker.js",
4  "name": "demo-app",
5  "compatibility_date": "2025-08-31",
6  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
7  "assets": {
8    "directory": ".open-next/assets",
9    "binding": "ASSETS"
10  },
11  "services": [
12    {
13      "binding": "WORKER_SELF_REFERENCE",
14      "service": "demo-app"
15    }
16  ]
17}
Copy

Step 3: Create open-next.config.ts (optional)

This file will also be auto-generated if not present during build. The R2 incremental cache is optional and requires R2 enabled on your Cloudflare account.

1import { defineCloudflareConfig } from "@opennextjs/cloudflare";
2import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";
3
4export default defineCloudflareConfig({
5  incrementalCache: r2IncrementalCache,
6});
Copy

Step 4: Update package.json Scripts

1{
2  "scripts": {
3    "dev": "next dev",
4    "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
5    "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
6    "upload": "opennextjs-cloudflare build && opennextjs-cloudflare upload",
7    "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
8  }
9}
Copy

Step 5: Remove export const runtime = "edge";

Edge runtime is not supported with @opennextjs/cloudflare. Make sure to remove this line from any of your source files before deploying.

This ensures your app runs in the Node.js runtime, which is fully compatible with OpenNext and Cloudflare Workers.

Step 6: Update .gitignore

Add .open-next to your .gitignore file to prevent the build output from being committed.

Step 7: Add Static Asset Caching

Create a public/_headers file with the following content:

/_next/static/*
 Cache-Control: public,max-age=31536000,immutable

This ensures that your static assets (JS, CSS) are cached for one year, improving performance for repeat visitors.

Step 8: Preview and Deploy

Preview your app locally first:

1npm run preview
Copy

Then deploy to Cloudflare Workers:

1npm run deploy
Copy

⚠️ Next.js Version & Known Issues

If you run into errors like:

1NextJS request failed. Error: An error occurred while loading the instrumentation hook
2at NextNodeServer.loadInstrumentationModule
Copy

This is a known issue (GitHub #667). The workaround is to downgrade your Next.js version to 15.3.

Other known issues and limitations with OpenNext on Cloudflare Workers can be found here: OpenNext Cloudflare Known Issues