Get Started

New apps

To create a new Next.js app, pre-configured to run on Cloudflare using @opennextjs/cloudflare, run:

npm create cloudflare@latest -- my-next-app --framework=next --experimental

Existing Next.js apps

1. Install @opennextjs/cloudflare

First, install @opennextjs/cloudflare (opens in a new tab):

npm install --save-dev @opennextjs/cloudflare@latest

2. Install Wrangler

Install the Wrangler CLI (opens in a new tab) as a devDependency:

npm install --save-dev wrangler@latest

3. Create a wrangler configuration file

A wrangler configuration file (opens in a new tab) is needed for your application to be previewed and deployed, it is also where you configure your Worker and define what resources it can access via bindings (opens in a new tab).

You can create one yourself in the root directory of your Next.js app with the name wrangler.json and the following content:

{
  "main": ".open-next/worker.js",
  "name": "my-app",
  "compatibility_date": "2024-12-30",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS",
  },
  "kv_namespaces": [
    // Create a KV binding with the binding name "NEXT_CACHE_WORKERS_KV"
    // to enable the KV based caching:
    // {
    //   "binding": "NEXT_CACHE_WORKERS_KV",
    //   "id": "<BINDING_ID>"
    // }
  ],
}

4. Add an open-next.config.ts file

Add a open-next.config.ts (opens in a new tab) file to the root directory of your Next.js app:

import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js";
import cache from "@opennextjs/cloudflare/kvCache";
 
const config: OpenNextConfig = {
  default: {
    override: {
      wrapper: "cloudflare-node",
      converter: "edge",
      // set `incrementalCache` to "dummy" to disable KV cache
      incrementalCache: async () => cache,
      tagCache: "dummy",
      queue: "dummy",
    },
  },
 
  middleware: {
    external: true,
    override: {
      wrapper: "cloudflare-edge",
      converter: "edge",
      proxyExternalRequest: "fetch",
    },
  },
};
 
export default config;

5. Add a .dev.vars file

Then, add a .dev.vars (opens in a new tab) file to the root directory of your Next.js app:

NEXTJS_ENV=development

The NEXTJS_ENV variable defines the environment to use when loading Next.js .env files. It defaults to "production" when not defined.

6. Update the package.json file

Add the following to the scripts field of your package.json file:

"build:worker": "opennextjs-cloudflare",
"dev:worker": "wrangler dev --port 8771",
"preview": "npm run build:worker && npm run dev:worker",
"deploy": "npm run build:worker && wrangler deploy",
"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts",

• npm run build:worker: Runs the @opennextjs/cloudflare (opens in a new tab) adapter. This first builds your app by running the build script in your package.json (Next.js apps use next build by default), and then transforms the build output to a format that you can run locally using Wrangler (opens in a new tab), and deploy to Cloudflare. The build command used by OpenNext can be overridden with the buildCommand option in your OpenNext config.
• npm run dev:worker: Takes the output generated by build:worker and runs it locally in workerd (opens in a new tab), the open-source Workers Runtime, allowing you to run the app locally in the same environment that it will run in production. If you instead run next dev, your app will run in Node.js, which is a different JavaScript runtime from the Workers runtime, with differences in behavior and APIs.
• npm run preview: Runs build:worker and then dev:worker, allowing you to quickly preview your app running locally in the Workers runtime, via a single command.
• npm run deploy: Builds your app, and then deploys it to Cloudflare
• cf-typegen: Generates a cloudflare-env.d.ts file at the root of your project containing the types for the env (opens in a new tab).

7. Add caching with Workers KV

See the Caching docs for information on enabling Next.js caching in your OpenNext project.

8. Remove any export const runtime = "edge"; if present

Before deploying your app, remove the export const runtime = "edge"; line from any of your source files.

The edge runtime is not supported yet with @opennextjs/cloudflare.

9. Add .open-next to .gitignore

You should add .open-next to your .gitignore file to prevent the build output from being committed to your repository.

10. Remove @cloudflare/next-on-pages (if necessary)

If your Next.js app currently uses @cloudflare/next-on-pages, you'll want to remove it, and make a few changes.

Uninstalling the @cloudflare/next-on-pages (opens in a new tab) package as well as the eslint-plugin-next-on-pages (opens in a new tab) package if present.

Remove any reference of these packages from your source and configuration files. This includes:

• setupDevPlatform() calls in your Next.js config file
• getRequestContext imports from @cloudflare/next-on-pages from your source files (those can be replaced with getCloudflareContext calls from @opennextjs/cloudflare)
• next-on-pages eslint rules set in your Eslint config file

11. Develop locally

You can continue to run next dev when developing locally.

During local development, you can access local versions of Cloudflare bindings as indicated in the bindings documentation.

In step 3, we also added the npm run preview:worker, which allows you to quickly preview your app running locally in the Workers runtime, rather than in Node.js. This allows you to test changes in the same runtime as your app will run in when deployed to Cloudflare.

12. Deploy to Cloudflare Workers

Either deploy via the command line:

npm run deploy:worker

Or connect a Github or Gitlab repository (opens in a new tab), and Cloudflare will automatically build and deploy each pull request you merge to your production branch.