Next.js on Pages: Another Full-Stack Framework Joins the Fold

Cloudflare Pages has added support for Next.js applications that opt into the Edge Runtime, making Next.js the fourth full-stack framework officially supported by the platform, alongside SvelteKit, Remix, and Qwik. The Pages platform began as a static hosting service, but last year's introduction of Pages Functions, powered by Cloudflare Workers, expanded it into full-stack territory. With Pages Functions' file-based routing, developers can add small server-side snippets or, as the adoption by other frameworks demonstrates, power an entire application.

Why the Edge Runtime Matters

Next.js' Edge Runtime, still experimental, produces a different type of application build than the standard Node.js server approach. Previously, Next.js apps relying on server-side rendering (SSR) required a Node.js server—heavyweight infrastructure that didn't align with Cloudflare Workers' V8-based architecture. When Next.js introduced the Edge Runtime in June 2022, it opened the door for this popular framework to run on Pages.

The Edge Runtime is being developed in coordination with the WinterCG standards, which aim to ensure interoperability across web platforms and give developers choice in where they run their applications without vendor lock-in concerns.

A caveat: existing Next.js apps built for Node.js won't automatically work on Pages. If an application depends on Node.js built-ins or long-running processes, it may not be supported just yet, as Cloudflare continues to expand its Node.js support. Still, the migration to the Edge Runtime is positioned as a worthwhile investment—such applications are cheaper to run, respond faster, and take advantage of the latest full-stack framework features. Combined with Cloudflare's data products (KV, Durable Objects, and D1), the edge is increasingly where developers will want to deploy.

Deploying a Next.js App

npx create-next-app@latest my-app

The default template includes a traditional Node.js-powered API route, which needs to be updated to use the Edge Runtime instead.

// pages/api/hello.js

// Next.js Edge API Routes: https://nextjs.org/docs/api-routes/edge-api-routes

export const config = {
  runtime: 'experimental-edge',
}

export default async function (req) {
  return new Response(
    JSON.stringify({ name: 'John Doe' }),
    {
      status: 200,
      headers: {
        'Content-Type': 'application/json'
      }
    }
  )
}

Since the Edge Runtime adopts Web API standards, the code should look familiar to anyone who has written a Cloudflare Worker. The global next.config.js configuration file also needs to be updated to use the Edge Runtime, which enables the getServerSideProps() API and SSR capabilities.

// next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    runtime: 'experimental-edge',
  },
  reactStrictMode: true,
  swcMinify: true,
}
module.exports = nextConfig

To deploy, push the project to a GitHub or GitLab repository, create a new Pages project, and select "Next.js" from the framework presets. This configures the build to use the @cloudflare/next-on-pages CLI, which transforms the project for Pages. Two environment requirements: set NODE_VERSION to 14 or greater, and add the compatibility flags streams_enable_constructors and transformstream_enable_standard_constructor. A detailed guide is available in Cloudflare's documentation.

Under the Hood

Compatibility Dates and Flags

Cloudflare Workers addresses versioning through compatibility dates and flags. While Pages Functions was in beta, it defaulted to the oldest Workers runtime version. Developers can now set these dates and flags per Pages project environment, with independent control for production and preview environments—allowing safe testing before a production rollout.

A screenshot of the Pages project settings page in the Cloudflare dashboard, showing the new compatibility date controls. The currently selected date is shown, alongside the list of other available dates.

Keeping the compatibility date recent opts into the latest Workers runtime features and bug fixes, while older dates remain supported indefinitely. Some Streams API functionality in the Workers Runtime is gated behind the flags mentioned above; these are scheduled to become default behavior on the 2022-11-30 compatibility date.

The @cloudflare/next-on-pages CLI

Vercel's Build Output API, introduced in July 2022, provides a "zero configuration" directory structure that its platform natively understands. Cloudflare hooks into this same API to consistently build and deploy Next.js projects. The open-source @cloudflare/next-on-pages CLI runs npx vercel build, producing a .vercel/output directory that conforms to the Build Output API, containing config.json, a static folder, and a functions folder. The CLI parses the config.json manifest and consolidates all functions into a single Pages Functions "advanced mode" _worker.js file, which Pages then deploys atop the static directory.

Cloudflare chose this approach partly as an implementation detail, but with broader ambitions. If more frameworks adopt the Build Output API, this CLI could provide automatic support for them on Pages. There's also discussion of offering other fixed directory structures on Pages, similar to the existing functions directory, that could reduce framework configuration needs.

Experimental Webpack Minification

When compiling from .vercel/output/functions to _worker.js, the CLI can optionally perform experimental minification to conserve space. Most accounts face a 1MB script size limit on Workers. Next.js's build process creates fully-isolated webpack-compiled functions in each directory within .vercel/output/functions, with significant code duplication:

let _ENTRIES = {};
(() => {
  // webpackBootstrap
})();

(self["webpackChunk_N_E"] = self["webpackChunk_N_E"] || []).push([100], {

  123: (() => {
    // webpack chunk #123
  }),
  234: (() => {
    // webpack chunk #234
  }),
  345: (() => {
    // webpack chunk #345
  }),

  // …lots of webpack chunks…

}, () => {
  // webpackRuntimeModules
}]);

export default {
  async fetch(request, env, ctx) {
    return _ENTRIES['some_function'].default.call(request);
  }
}

Each function contains everything needed for deployment, with most logic in webpack chunks—but much of that code is shared between sibling functions. Naively deploying them together quickly hits the 1MB limit. The --experimental-minify flag addresses this by analyzing reused webpack chunks, extracting shared code to a common location so the compiler (esbuild) can combine everything efficiently without duplication. The feature remains experimental while Cloudflare works on making it both efficient and bug-free.

Looking Ahead

Pages Functions, in beta for nearly a year, is approaching general availability. Remaining items include analytics, logging, and billing—for which a Workers Paid plan option removes the beta's request limits starting November 15. Page Functions will also gain Wasm support, unlocking additional use cases for full-stack applications.

For developers wanting to experiment, deploying a Next.js Edge Runtime application to Cloudflare Pages follows the steps above or the documentation guide. Issues with --experimental-minify or anything else can be reported through the usual channels.