@cloudflare/next-on-pages is a CLI tool that helps you build and develop Next.js applications to run on the Cloudflare Pages platform. This allows you to integrate your application with other Cloudflare products such as KV, D1, R2, and Durable Objects. Although most Next.js features are supported, some may not be included. For more information, refer to the Supported Versions and Features document.
Using @cloudflare/next-on-pages, you can easily bundle and deploy your Next.js application on Cloudflare Pages. In this blog, we will discuss how to use @cloudflare/next-on-pages to deploy your Next.js application on Cloudflare Pages.
Let's get started with the quick start guide on how to bundle and deploy a new or existing Next.js application using @cloudflare/next-on-pages.
1. Create Next.js App:
Before you start using @cloudflare/next-on-pages, you need to have a Next.js project that you want to deploy. You can create a new project using the following command:
npx create-next-app@latest my-next-appOnce you have created the project, change your current directory to the newly created project by running:
cd my-next-appConfigure the Application to Use Edge Runtime:
To run your application on Cloudflare Pages, you need to set it to use the Edge Runtime. Ensure that all the files in your application containing server-side code export a config object specifying the use of the Edge Runtime:
export const config = {
runtime: 'edge',
};Also, ensure that your application is not using any unsupported APIs, and its API routes are defined as Edge API Routes.
Deploy Your Application to Cloudflare Pages:
You can deploy your application to Cloudflare Pages via automatic Git integration. 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.
- Provide the following options: Build command: npx @cloudflare/next-on-pages --experimental-minify Build output directory: .vercel/output/static
- In the Environment variables (advanced) section, add a new variable named NODE_VERSION set to 16 or greater (18 is not supported yet, See Build Image Update Discussion).
- 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 for both the 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 _worker.js file (as indicated in Local Development) and publish your application manually via the wrangler's pages publish command instead (but you'll still need to set the nodejs_compat flag for your project in the Cloudflare dashboard).
Local Development:
To run the CLI locally, run the following command:
npx @cloudflare/next-on-pagesThis command will build your Next.js application and produce a .vercel/output/static directory that you can use with Wrangler:
npx wrangler pages dev .vercel/output/static --compatibility-flag=nodejs_compatRunning npx @cloudflare/next-on-pages --help will display a useful help message that 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
If still you have confusion, you can checkout the examples here on how to use Next.js features with @cloudflare/next-on-pages see the Examples document:
github.com/cloudflare/next-on-pages/blob/main/docs/examples.md