Supported features

Supported Next.js versions

@cloudflare/next-on-pages supports all minor and patch version of Next.js 13 and 14. We regularly run manual and automated tests to ensure compatibility.

Node.js API support

Next.js has two "runtimes" ↗ — "Edge" and "Node.js".

The @cloudflare/next-on-pages adapter supports only the edge "runtime".

The @opennextjs/cloudflare adapter ↗, which lets you build and deploy Next.js apps to Cloudflare Workers, supports the Node.js "runtime" from Next.js. When you use it, you can use the full set of Node.js APIs that Cloudflare Workers provide.

@opennextjs/cloudflare is pre 1.0, and still in active development. As it approaches 1.0, it will become the clearly better choice for most Next.js apps, since Next.js has been engineered to only support its Node.js "runtime" for many newly introduced features.

Refer to the OpenNext docs ↗ and the Workers vs. Pages compatibility matrix for more information to help you decide which to use.

Supported Node.js APIs when using `@cloudflare/next-on-pages`

When you use @cloudflare/next-on-pages, your Next.js app must use the "edge" runtime from Next.js. The Workers runtime supports a broad set of Node.js APIs — but the Next.js Edge Runtime code intentionally constrains this ↗. As a result, only the following Node.js APIs will work in your Next.js app:

buffer
events
assert
util
async_hooks

If you need to use other APIs from Node.js, you should use @opennextjs/cloudflare ↗ instead.

Supported Features

Routers

Cloudlflare recommends using the App router ↗ from Next.js.

Cloudflare also supports the older Pages ↗ router from Next.js.

next.config.mjs Properties

next.config.js — app router ↗ and `next.config.js - pages router ↗

Option	Next Docs	Support
appDir	app ↗	✅
assetPrefix	pages ↗, app ↗	🔄
basePath	pages ↗, app ↗	✅
compress	pages ↗, app ↗	`N/A`¹
devIndicators	pages ↗, app ↗	`N/A`²
distDir	pages ↗, app ↗	`N/A`³
env	pages ↗, app ↗	✅
eslint	pages ↗, app ↗	✅
exportPathMap	pages ↗, app ↗	`N/A`⁴
generateBuildId	pages ↗, app ↗	✅
generateEtags	pages ↗, app ↗	🔄
headers	pages ↗, app ↗	✅
httpAgentOptions	pages ↗, app ↗	`N/A`
images	pages ↗, app ↗	✅
incrementalCacheHandlerPath	app ↗	🔄
logging	app ↗	`N/A`⁵
mdxRs	app ↗	✅
onDemandEntries	pages ↗, app ↗	`N/A`⁶
optimizePackageImports	app ↗	✅/`N/A`⁷
output	pages ↗, app ↗	`N/A`⁸
pageExtensions	pages ↗, app ↗	✅
Partial Prerendering (experimental)	app ↗	❌⁹
poweredByHeader	pages ↗, app ↗	🔄
productionBrowserSourceMaps	pages ↗, app ↗	🔄¹⁰
reactStrictMode	pages ↗, app ↗	❌¹¹
redirects	pages ↗, app ↗	✅
rewrites	pages ↗, app ↗	✅
Runtime Config	pages ↗, app ↗	❌¹²
serverActions	app ↗	✅
serverComponentsExternalPackages	app ↗	`N/A`¹³
trailingSlash	pages ↗, app ↗	✅
transpilePackages	pages ↗, app ↗	✅
turbo	pages ↗, app ↗	🔄
typedRoutes	app ↗	✅
typescript	pages ↗, app ↗	✅
urlImports	pages ↗, app ↗	✅
webpack	pages ↗, app ↗	✅
webVitalsAttribution	pages ↗, app ↗	✅

- ✅: Supported
- 🔄: Not currently supported
- ❌: Not supported
- N/A: Not applicable

Internationalization

Cloudflare also supports Next.js' internationalized (i18n) routing ↗.

Rendering and Data Fetching

Incremental Static Regeneration

If you use Incremental Static Regeneration (ISR)¹⁴, @cloudflare/next-on-pages will use static fallback files that are generated by the build process.

This means that your application will still correctly serve your ISR/prerendered pages (but without the regeneration aspect). If this causes issues for your application, change your pages to use server side rendering (SSR) instead.

Background

ISR pages are built by the Vercel CLI to generate Vercel Prerender Functions ↗. These are Node.js serverless functions that can be called in the background while serving the page from the cache.

It is not possible to use these with Cloudflare Pages and they are not compatible with the edge runtime ↗ currently.

Dynamic handling of static routes

@cloudflare/next-on-pages supports standard statically generated routes.

It does not support dynamic Node.js-based on-demand handling of such routes.

For more details see:

Caching and Data Revalidation

Revalidation and next/cache are supported on Cloudflare Pages and can use various bindings. For more information, see our caching documentation.

compression: Cloudflare applies Brotli or Gzip compression automatically. When developing locally with Wrangler, no compression is applied. ↩
dev indicators: If you're developing using wrangler pages dev, it hard refreshes your application the dev indicator doesn't appear. If you run your app locally using next dev, this option works fine. ↩
setting custom build directory: Applications built using @cloudflare/next-on-pages don't rely on the .next directory so this option isn't really applicable (the @cloudflare/next-on-pages equivalent is to use the --outdir flag). ↩
exportPathMap: Option used for SSG not applicable for apps built using @cloudflare/next-on-pages. ↩
logging: If you're developing using wrangler pages dev, the extra logging is not applied (since you are effectively running a production build). If you run your app locally using next dev, this option works fine. ↩
onDemandEntries: Not applicable since it's an option for the Next.js server during development which we don't rely on. ↩
optimizePackageImports: @cloudflare/next-on-pages performs chunks deduplication and provides an implementation based on modules lazy loading, based on this applying an optimizePackageImports doesn't have an impact on the output produced by the CLI. This configuration can still however be used to speed up the build process (both when running next dev or when generating a production build). ↩
output: @cloudflare/next-on-pages works with the standard Next.js output, standalone is incompatible with it, export is used to generate a static site which doesn't need @cloudflare/next-on-pages to run. ↩
Partial Prerendering (experimental): As presented in the official Next.js documentation ↗: Partial Prerendering is designed for the Node.js runtime only., as such it is fundamentally incompatibly with @cloudflare/next-on-pages (which only works on the edge runtime). ↩
productionBrowserSourceMaps: The webpack chunks deduplication performed by @cloudflare/next-on-pages doesn't currently preserve source maps in any case so this option can't be implemented either. In the future we might try to preserver source maps, in such case it should be simple to also support this option. ↩
reactStrictMode: Currently we build the application so react strict mode (being a local dev feature) doesn't work either way. If we can make strict mode work, this option will most likely work straight away. ↩
runtime configuration: We could look into implementing the runtime configuration but it is probably not worth it since it is a legacy configuration and environment variables should be used instead. ↩
serverComponentsExternalPackages: This option is for applications running on Node.js so it's not relevant to applications running on Cloudflare Pages. ↩
Incremental Static Regeneration (ISR) ↗ is a rendering mode in Next.js that allows you to automatically cache and periodically regenerate pages with fresh data. ↩

Was this helpful?

Community
X
Discord
YouTube
GitHub