Skip to content
Cloudflare Docs
We recommend using Cloudflare Workers for new projects. For existing Pages projects, see our migration guide and compatibility matrix.
Close

Get started

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

New apps

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

Terminal window
npm create cloudflare@latest -- my-next-app --framework=next --platform=pages

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 ↗:

Terminal window
npm i -D @cloudflare/next-on-pages

2. Add Wrangler file

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

{
  "name": "my-app",
  "compatibility_date": "2024-09-23",
  "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:

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

Terminal window
npm i -D 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"
  ]
}