02_opennext_deployment_to_cloudflare

Deploying OpenNext to Cloudflare

This guide provides the standard procedure for deploying a Next.js application using the OpenNext adapter to Cloudflare Pages.

Prerequisites

• The project is a Next.js application.
• The open-next package is installed as a dev dependency.
• The package.json has a build script configured to run open-next build.
• The Cloudflare account is set up, and the site is configured.
• You have connected the project’s GitHub repository to Cloudflare Pages.

OpenNext Configuration

The open-next.config.ts file in the project root allows for customization of the build output. A standard configuration might look like this:

import { defineConfig } from "open-next/config";
 
export default defineConfig({
  // Default configuration is usually sufficient.
  // We can add overrides here if needed, for example:
  // function: {
  //   patterns: ["/api/v1/*"],
  //   memory: 512,
  // },
});

The build command in package.json should be:

"scripts": {
  "build": "open-next build"
}

This command will:

1. Run next build.
2. Transform the output into a format compatible with Cloudflare Pages, creating a .open-next directory.
   • .open-next/assets: Static assets to be served by Cloudflare Pages.
   • .open-next/server-function: The server-side logic packaged as a Cloudflare Worker.
   • .open-next/image-optimization-function: A separate Worker for Next.js image optimization.

Cloudflare Pages Configuration

1. Create a New Application:
   • In the Cloudflare dashboard, navigate to Workers & Pages.
   • Click Create application > Pages > Connect to Git.
2. Select Repository:
   • Choose the GitHub repository for your project.
3. Configure the Build:
   • Production Branch: Set to main.
   • Build command: npm run build
   • Build output directory: .open-next/assets
4. Environment Variables:
   • Add any necessary environment variables for the production build (e.g., NEXT_PUBLIC_API_URL).
   • Important: Do not store secrets as plain text environment variables. Follow our guide for Managing Secrets in Cloudflare.
5. Deploy:
   • Save and Deploy. Cloudflare will now build and deploy your application.

Post-Deployment Steps: Binding Functions

OpenNext creates server-side functions that are not automatically bound by the standard Pages build process. We need to manually ensure the functions are configured correctly.

1. Navigate to Pages Settings:
   • Go to your Pages project settings.
2. Functions:
   • Under Functions > Function-invocation routes, you may need to ensure that routes intended for the server function are correctly routed. OpenNext typically handles this with a _routes.json file, but it’s good to verify.
   • Ensure the server-side and image optimization functions generated by OpenNext are correctly associated with your Pages project.

Staging/Preview Environments

• Cloudflare Pages automatically creates a unique preview deployment for every Pull Request.
• This is a key benefit, as it allows us to test changes in a production-like environment before merging to main.
• Environment variables for preview deployments can be configured separately in the Pages settings, allowing you to use staging or mock services for previews.

This setup provides a robust, scalable, and cost-effective way to run Next.js applications, leveraging the best of Cloudflare’s serverless platform.