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](https://developers.cloudflare.com/workers/frameworks/), including apps that use the Node.js "runtime" from Next.js. This allows you to use the [Node.js APIs that Cloudflare Workers provides](https://developers.cloudflare.com/workers/runtime-apis/nodejs/#built-in-nodejs-runtime-apis), and ensures compatibility with a broader set of Next.js features and rendering modes.

Refer to the [OpenNext docs for the `@opennextjs/cloudflare` adapter](https://opennext.js.org/cloudflare) to learn how to get started.

## New apps

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

* npm

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

* pnpm

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

* yarn

  ```sh
  yarn create cloudflare my-next-app --framework=next
  ```

For more guidance on developing your app, refer to [Bindings](https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/bindings/) or the [Next.js documentation](https://nextjs.org).

***

## Existing apps

### 1. Install next-on-pages

First, install [@cloudflare/next-on-pages](https://github.com/cloudflare/next-on-pages):

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

### 2. Add Wrangler file

Then, add a [Wrangler configuration file](https://developers.cloudflare.com/pages/functions/wrangler-configuration/) to the root directory of your Next.js app:

* wrangler.jsonc

  ```jsonc
  {
    "name": "my-app",
    "compatibility_date": "2024-09-23",
    "compatibility_flags": [
      "nodejs_compat"
    ],
    "pages_build_output_dir": ".vercel/output/static"
  }
  ```

* wrangler.toml

  ```toml
  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](https://developers.cloudflare.com/workers/runtime-apis/bindings/).

### 3. Update `next.config.mjs`

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

```diff
 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](https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/bindings/) in local development.

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

Next.js has [two "runtimes"](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) — "Edge" and "Node.js". When you run your Next.js app on Cloudflare, you [can use available Node.js APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) — 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:

```js
export const runtime = "edge";
```

### 5. Update `package.json`

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

```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](https://github.com/cloudflare/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:

```sh
npm run deploy
```

Or [connect a Github or Gitlab repository](https://developers.cloudflare.com/pages/get-started/git-integration/), 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.

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

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

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

## Related resources

* [Bindings](https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/bindings/)
* [Troubleshooting](https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/troubleshooting/)
