@imsh4yy/next-on-pages

@cloudflare/next-on-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.

Quick Start

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

1. Select your Next.js app

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

Note on the Next.js version

We have confirmed support for the current version of Next.js at the time of writing, 13.4.2. Although we'll endeavor to keep support for newer versions, we cannot guarantee that we'll always be up-to-date with the latest version. If you experience any problems with @cloudflare/next-on-pages, you may wish to try pinning to 13.4.2 while we work on supporting any recent breaking changes.

2. Configure the application to use the Edge Runtime

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.

3. Deploy your application to Cloudflare Pages

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).

Note: When deploying via the Git integration, for better compatibility with tools such as yarn and pnpm we recommend using the Build system version 2 (that is the default so no action is required).

Local development

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.

Local development in watch mode

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

Examples

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

More Information

For more information on the project please check out the README in the next-on-pages github repository.