Build, develop, and deploy Next.js apps for Cloudflare Pages.

@cloudflare/next-on-pages is a CLI tool that you can use to build and develop Next.js applications so that they can run on the Cloudflare Pages platform (and integrate with Cloudflare's various other product offerings, such as KV, D1, R2, and Durable Objects).

This tool is a best-effort library implemented by the Cloudflare team and the community. As such, most, but not all, Next.js features are supported. See the Supported Versions and Features document for more details.

This section describes how to bundle and deploy a (new or existing) Next.js application to Cloudflare Pages, using @cloudflare/next-on-pages.

To start using @cloudflare/next-on-pages, you must have a Next.js project that you wish to deploy. If you already have one, change to its directory. Otherwise, you can use the create-next-app command to start a new one.

npx create-next-app@latest my-next-app
cd my-next-app

For your application to run on Cloudflare Pages, it needs to opt in to use the Edge Runtime for routes containing server-side code (e.g. API Routes or pages that use getServerSideProps). To do this, export a runtime route segment config option from each file, specifying that it should use the Edge Runtime.

export const runtime = 'edge';

For more examples of this and for Next.js versions prior to v13.3.1, take a look at our examples document. Additionally, ensure that your application is not using any unsupported APIs or features.

To deploy your application to Cloudflare Pages, you need to install the @cloudflare/next-on-pages package.

npm install -D @cloudflare/next-on-pages

Then you can deploy to Cloudflare Pages via the automatic Git integration. To do so, start by committing and pushing your application's code to a GitHub/GitLab repository.

Next, in the Cloudflare Dashboard, create a new Pages project:

• Navigate to the project creation pages (Your account Home > Pages > Create a project > Connect to Git).
• Select the GitHub/GitLab repository you pushed your code to.
• Choose a project name and your production branch.
• Select Next.js as the Framework preset and provide the following options:

  Option	Value
  Build command	npx @cloudflare/next-on-pages@1
  Build output directory	.vercel/output/static

• In the Environment variables (advanced) section, add a new variable named NODE_VERSION set to 16 or greater.
• Click on Save and Deploy to start the deployment (this first deployment won't be fully functional as the next step is also necessary).
• Go to the Pages project settings page (Settings > Functions > Compatibility Flags), add the nodejs_compat flag for both production and preview, and make sure that the Compatibility Date for both production and preview is set to at least 2022-11-30.

If you don't want to set up a Git repository, you can build your application (as indicated in Local Development) and publish it manually via the wrangler pages publish command instead (you'll still need to set the nodejs_compat flag for your project in the Cloudflare dashboard).

To run the CLI locally, simply run:

npx @cloudflare/next-on-pages

This command will build your Next.js application and produce a .vercel/output/static directory which you can then use with Wrangler:

npx wrangler pages dev .vercel/output/static --compatibility-flag=nodejs_compat

Running npx @cloudflare/next-on-pages --help will display a useful help message which will detail the various additional options the CLI offers.

If you want to work on your Next.js application while using @cloudflare/next-on-pages, run the CLI in watch mode with:

npx @cloudflare/next-on-pages --watch

Then in a separate terminal run:

npx wrangler pages dev .vercel/output/static --compatibility-flag=nodejs_compat

To see some examples on how to use Next.js features with @cloudflare/next-on-pages, see the Examples document.

If you want to contribute to this project please refer to the Contributing document.

Extra references you might be interested in:

• Blog post

  The original blog post introducing @cloudflare/next-on-pages (24/10/2022), it goes into details on the inspiration for this package and provides some details on how it works.

• Cloudflare Next.js Guide

  Cloudflare guide on how to create and deploy a Next.js application. The application can be either static (and deployed as simple static assets) or dynamic using the edge runtime (using @cloudflare/next-on-pages).

• Technical Documentation

  Explanations and insights into how @cloudflare/next-on-pages works, design decisions behind different aspects, and how it handles different Next.js features.