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:

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