supported.md

Supported Versions and Features

Operating Systems

@cloudflare/next-on-pages can be run on Linux, Mac OS and Windows but its usage under the latter is discouraged as we've noticed that one of the CLI's dependencies, the Vercel CLI (used to build the Next.js application) seems not to work reliably on Windows. If you need to run @cloudflare/next-on-pages on Windows we advise you to run it under the Windows Subsystem for Linux.

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 such compatibility.

Next.js canary versions not actively being tested and we don't currently extend support to these versions.

Node.js

Next.js offers two different runtimes for your application's routes: Node.js and Edge.

Routes using the Node.js runtime get built as Node.js serverless functions, such are fundamentally incompatible with the Cloudflare network and so only routes using the Edge runtime are supported when using @cloudflare/next-on-pages.

The Cloudflare workers runtime supports certain Node.js APIs, but currently Next.js in its Edge runtime only supports a subset of them, resulting in only the following Node.js built-in modules being currently supported in @cloudflare/next-on-pages:

• buffer
• events
• assert
• util
• async_hooks

External Packages

You are free to use any external npm package with your Next.js application as long as it doesn't use:

• unsupported Node.js APIs (see above)
• JavaScript APIs disabled by Cloudflare due to security concerns
• features not supported by @cloudflare/next-on-pages (see below)

Supported Features

Routers

Both the Pages and App routers are supported, however we recommend using the App router as there are a few unsupported features in the Pages one (including custom error pages), and since the latter is not the recommended one by the Next.js team, there is a good chance that it won't be improved/worked on to such a degree to allows us to increase our support of it.

The App router should be fully supported, but unfortunately a few of its features aren't currently supported (because of Vercel implementation details that are outside of our control) like for example custom not-found pages with server side runtime logic.

To check the latest state of the routers and possible missing features you can check our GitHub app router and pages router issues.

Build Output Configuration

The following options have been gathered from the Vercel Build Output API (v3) documentation:

config.json property	Support
version	3
routes src	✅
routes dest	✅
routes headers	✅
routes methods	✅
routes continue	✅
routes caseSensitive	✅
routes check	✅
routes status	✅
routes has	✅
routes missing	✅
routes locale	✅
routes middlewarePath	✅
images1	✅
wildcard	✅
overrides	✅
cache	❌
crons	❌

- ✅: Supported
- 🔄: Not currently supported, but it's probably possible and we may add support in the future
- ❌: Not supported and unlikely to be supported in the future

• 1 - images: If you want to use next/image, there are two options; allow the library to take care of incoming requests, or using a custom loader. Requests are intercepted in the router and image resizing is attempted to be used (due to limitations with Pages, it is not currently possible to use image resizing) - if image resizing is not available, it falls back to fetching the normal image URL. Alternatively, you can provide your own custom loader and use Cloudflare Image Resizing, as per Cloudflare's Image Resizing documentation.

next.config.mjs Properties

The following options have been gathered from the Next.js' next.config.js app and pages documentations.

Option	Next Docs	Support
appDir	app	✅
assetPrefix	pages, app	🔄
basePath	pages, app	✅
compress	pages, app	N/A1
devIndicators	pages, app	N/A2
distDir	pages, app	N/A3
env	pages, app	✅
eslint	pages, app	✅
exportPathMap	pages, app	N/A4
generateBuildId	pages, app	✅
generateEtags	pages, app	🔄
headers	pages, app	✅
httpAgentOptions	pages, app	N/A
images	pages, app	✅
incrementalCacheHandlerPath	app	🔄
logging	app	N/A5
mdxRs	app	✅
onDemandEntries	pages, app	N/A6
optimizePackageImports	app	✅/N/A7
output	pages, app	N/A8
pageExtensions	pages, app	✅
Partial Prerendering (experimental)	app	❌9
poweredByHeader	pages, app	🔄
productionBrowserSourceMaps	pages, app	🔄10
reactStrictMode	pages, app	❌11
redirects	pages, app	✅
rewrites	pages, app	✅
Runtime Config	pages, app	❌12
serverActions	app	✅
serverComponentsExternalPackages	app	N/A13
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, but it's probably possible and we may add support in the future
- ❌: Not supported and unlikely we ever will support this
- N/A: Not applicable

• 1 - compression: Cloudflare applies gzip or brotli compression automatically. When developing locally with Wrangler, no compression is applied.

• 2 - 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.

• 3 - 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).

• 4 - exportPathMap: Option used for SSG not applicable for apps built using @cloudflare/next-on-pages.

• 5 - 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.

• 6 - onDemandEntries: Not applicable since it's an option for the Next.js server during development which we don't rely on.

• 7 - 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).

• 8 - 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.

• 9 - 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).

• 10 - 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.

• 11 - 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.

• 12 - 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.

• 13 - serverComponentsExternalPackages: This option is for applications running on Node.js so it's not relevant to applications running on Cloudflare Pages.

Internationalization

Besides the above mentioned next.config.js properties, there is also the i18n one, that is also fully supported meaning that @cloudflare/next-on-pages does support Next.js' built-in internationalization system. For more details on the option see the Next.js Internationalization documentation.

Rendering and Data Fetching

Incremental Static Regeneration

Incremental Static Regeneration (ISR) is a rendering mode in Next.js that allows you to automatically cache and periodically regenerate pages with fresh data. Next.js does not support building ISR pages for the edge runtime, and as such, pages should be changed to use server side rendering (SSR) instead.

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.

In case the Vercel build process generates predendered pages for your application, @cloudflare/next-on-pages will use static fallback files that are generated by the build process so that your application will still correctly serve your ISR/prerendered pages (but without the regeneration aspect).

Dynamic handling of static routes

@cloudflare/next-on-pages supports standard statically generated routes, it does however not support dynamic Node.js-based on-demand handling of such routes.

For more details see:

• troubleshooting generateStaticParams
• troubleshooting getStaticPaths

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.