A Dual Leap in Performance and Flexibility：The Ultimate Guide to Seamlessly Migrating Next.js Applications to Cloudflare Pages

Authors

At the early stages of building frontend applications with Next.js, convenient deployment platforms like Vercel are often our first choice. However, as the user base grows, the cost of using Vercel increases accordingly. At this point, migrating your Next.js application to Cloudflare Pages becomes a smart move. Not only can this significantly reduce deployment costs, but it also leverages Cloudflare’s edge computing and efficient CDN to dramatically improve global response times, giving your application a major performance boost.

However, the migration process isn’t always smooth. You may encounter some common challenges, such as issues parsing MDX files, database connections not compatible with Edge Runtime, and compatibility problems with npm build versions. While these issues might seem tricky, they are solvable.

In this article, we will walk you through each step of the migration process, providing effective solutions to help you easily overcome these challenges. So, buckle up as we embark on this exciting migration journey!

Part 1: Preparations

  1. First, install the @cloudflare/next-on-pages package:
npm install --save-dev @cloudflare/next-on-pages

This package is a custom tool by Cloudflare designed to help Next.js applications run on Cloudflare Pages, ensuring compatibility.

  1. Then, create a wrangler.toml file in the root directory of your project with the following content:
name = "my-app"
compatibility_date = "2024-07-29"
compatibility_flags = ["nodejs_compat"]
pages_build_output_dir = ".vercel/output/static"

This file defines compatibility settings for the project and informs Cloudflare Pages how to handle the output files. Pay special attention to the compatibility_flags, which allow some Node.js APIs to run on Cloudflare.

  1. Update the next.config.mjs file:
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;
  1. Modify the route.ts and layout.ts files by adding the following line:
export const runtime = 'edge';
  1. Finally, add Cloudflare build scripts in package.json to ensure proper build and preview of your project:
"scripts": {
  "pages:build": "npx @cloudflare/next-on-pages",
  "preview": "npm run pages:build && wrangler pages dev",
  "deploy": "npm run pages:build && wrangler pages deploy"
}

These scripts handle building, previewing, and deploying the project. pages:build converts the Next.js app into a format suitable for Cloudflare Pages, and preview allows local testing through Cloudflare’s Workers Runtime.

All steps are officially documented: Get started | Full-stack (SSR) | Next.js apps

Part 2: Drizzle ORM and Neon/PostgreSQL Connection Issues

Problem: Drizzle ORM client not supporting Edge Runtime

If you’re using Drizzle ORM to connect a Neon database in your Next.js project, you might find it doesn’t work correctly on Cloudflare.

Solution: Use @neondatabase/serverless

To resolve this, you can use Neon’s PostgreSQL service, which works with Cloudflare’s Edge Runtime. Neon provides a package called @neondatabase/serverless, designed for serverless environments like Cloudflare Pages.

First, install the Neon serverless driver:

npm install @neondatabase/serverless

Then, replace the db.ts file with the following code to use @neondatabase/serverless:

import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';

const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle(sql);

This approach allows your database connection to run in the Edge Runtime. More details can be found in Drizzle ORM - PostgreSQL.

Part 3: Cloudflare Build Failures

Problem: Successful local build but failed Cloudflare build

When building a Next.js project on Cloudflare Pages, you might encounter npm version compatibility issues. This occurs because the default npm version on Cloudflare Pages might be incompatible with your project dependencies, leading to build failures.

Solution: Specify npm build version

To fix this, add a .node-version file in the project’s root directory and specify the Node.js version you want to use. For example:

18.18.2

This ensures that Cloudflare Pages will use the specified Node.js version during the build process, avoiding version compatibility issues.

Part 4: Solving MDX File Rendering Issues

MDX file rendering on Cloudflare may rely on packages not supported in the edge environment. If you use MDX-related functionality, you will need to make some adjustments. For more details, you can refer to my previous blog post:

Solving MDX Deployment Issues on Cloudflare Pages: A Guide to Fixing EvalError | Innovation for Bytes

Part 5: Conclusion

Migrating a Next.js application to Cloudflare Pages can reduce deployment costs, but the technical challenges should not be overlooked. In this article, we discussed issues with MDX file rendering, Drizzle ORM connections to Neon databases, and resolving npm build version compatibility problems.

Additionally, we followed Cloudflare’s official migration steps to ensure a smooth process. If you’re considering a similar migration, I hope this article provides valuable insights and guidance.

If you have any further questions or suggestions, feel free to leave a comment below!

Share this content