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:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "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/kv-cache";
 
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:

"preview": "opennextjs-cloudflare && wrangler dev",
"deploy": "opennextjs-cloudflare && wrangler deploy",
"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts",

• npm run preview: Builds your app and serves it locally, 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.

Modify your Next.js configuration file to import and call the initOpenNextCloudflareForDev utility from the @opennextjs/cloudflare package. This makes sure that the Next.js dev server can optimally integrate with the open-next cloudflare adapter and it is necessary for using bindings during local development.

This is an example of a Next.js configuration file calling the utility:

// next.config.mjs
 
import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
 
initOpenNextCloudflareForDev();
 
/** @type {import('next').NextConfig} */
const nextConfig = {};
 
export default nextConfig;

After having added the initOpenNextCloudflareForDev() call in your Next.js configuration file, you will be able, during local development, to access in any of your server code, local versions of Cloudflare bindings as indicated in the bindings documentation.

In step 3, we also added the npm run preview, 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

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.