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

2. Install Wrangler, and add a wrangler.toml file

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

npm install -D wrangler@latest

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

main = ".worker-next/index.mjs"
name = "my-app"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]
assets = { directory = ".worker-next/assets", binding = "ASSETS" }

wrangler.toml is where you configure your Worker and define what resources it can access via bindings (opens in a new tab).

3. Update package.json

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

"build:worker": "cloudflare",
"dev:worker": "wrangler dev --port 8771",
"preview:worker": "npm run build:worker && npm run dev:worker",
"deploy:worker": "npm run build:worker && wrangler deploy"

• npm run build:worker: Runs the @opennextjs/cloudflare (opens in a new tab) adapter. This first builds your app by running next build behind the scenes, 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.
• 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:worker: 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

4. Add caching with Workers KV

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

5. 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.

Remove export const runtime = "edge";

Before deploying your app, remove the export const runtime = "edge"; line from your next.config.js file. This line is not needed when using @opennextjs/cloudflare.

Add .worker-next to .gitignore

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

Uninstall @cloudflare/next-on-pages

You should uninstall @cloudflare/next-on-pages and remove any references to it.

In package.json:

"scripts": {
-    "pages:build": "npx @cloudflare/next-on-pages",
-    "preview": "npm run pages:build && wrangler pages dev",
-    "deploy": "npm run pages:build && wrangler pages deploy"
 
"devDependencies": {
-    "@cloudflare/next-on-pages": "*",

(remember to also remove eslint-plugin-next-on-pages (opens in a new tab) from your .eslintrc.js file)

You no longer need to call setupDevPlatform() in your next.config.mjs file:

And you'll want to replace any uses of getRequestContext from @cloudflare/next-on-pages with getCloudflareContext from @opennextjs/cloudflare:

- import { getRequestContext } from "@cloudflare/next-on-pages";
+ import { getCloudflareContext } from "@opennextjs/cloudflare";

6. 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.

7. 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.