Skip to content
Cloudflare Docs

Get started

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

New apps

Section titled “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

Section titled “Existing apps”

1. Install next-on-pages

Section titled “1. Install next-on-pages”

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

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

2. Add Wrangler file

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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 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"
  ]
}
Section titled “Related resources”