Get started

Learn how to deploy full-stack (SSR) Next.js apps to Cloudflare Pages.

Note

You can now also deploy Next.js apps to Cloudflare Workers ↗, including apps that use the Node.js "runtime" from Next.js. This allows you to use the Node.js APIs that Cloudflare Workers provides, and ensures compatibility with a broader set of Next.js features and rendering modes.

Refer to the OpenNext docs for the @opennextjs/cloudflare adapter ↗ to learn how to get started.

New apps

To create a new Next.js app, pre-configured to run on Cloudflare, run:

npm

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

yarn

yarn create cloudflare@latest my-next-app --framework=next

pnpm

pnpm create cloudflare@latest my-next-app --framework=next

For more guidance on developing your app, refer to Bindings or the Next.js documentation ↗.

---

Existing apps

1. Install next-on-pages

First, install @cloudflare/next-on-pages ↗:

npm install --save-dev @cloudflare/next-on-pages

2. Add wrangler.toml file

Then, add a wrangler.toml file to the root directory of your Next.js app:

wrangler.toml

name = "my-app"
compatibility_date = "2024-07-29"
compatibility_flags = ["nodejs_compat"]
pages_build_output_dir = ".vercel/output/static"

wrangler.json

{
  "name": "my-app",
  "compatibility_date": "2024-07-29",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "pages_build_output_dir": ".vercel/output/static"
}

This is where you configure your Pages project and define what resources it can access via bindings.

3. Update next.config.mjs

Next, update the content in your next.config.mjs file.

next.config.mjs

 import { setupDevPlatform } from '@cloudflare/next-on-pages/next-dev';

/** @type {import('next').NextConfig} */
const nextConfig = {};

 if (process.env.NODE_ENV === 'development') {
   await setupDevPlatform();
 }

export default nextConfig;

These changes allow you to access bindings in local development.

4. Ensure all server-rendered routes use the Edge Runtime

Next.js has two "runtimes" ↗ — "Edge" and "Node.js". When you run your Next.js app on Cloudflare, you can use available Node.js APIs — but you currently can only use Next.js' "Edge" runtime.

This means that for each server-rendered route — ex: an API route or one that uses getServerSideProps — you must configure it to use the "Edge" runtime:

export const runtime = "edge";

5. Update package.json

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

package.json

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

• npm run pages:build: Runs next build, and then transforms its output to be compatible with Cloudflare Pages.
• npm run preview: Builds your app, and runs it locally in workerd ↗, the open-source Workers Runtime. (next dev will only run your app in Node.js)
• npm run deploy: Builds your app, and then deploys it to Cloudflare

6. Deploy to Cloudflare Pages

Either deploy via the command line:

npm run deploy

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

7. (Optional) Add eslint-plugin-next-on-pages

Optionally, you might want to add eslint-plugin-next-on-pages, which lints your Next.js app to ensure it is configured correctly to run on Cloudflare Pages.

npm install --save-dev eslint-plugin-next-on-pages

Once it is installed, add the following to .eslintrc.json:

.eslintrc.json

{
  "extends": [
    "next/core-web-vitals",
    "plugin:eslint-plugin-next-on-pages/recommended"
  ],
  "plugins": [
    "eslint-plugin-next-on-pages"
  ]
}

Related resources

• Bindings
• Troubleshooting

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!