@cloudflare/next-on-pages
is a CLI tool that you can use to build and develop Next.js applications so that they can run on the Cloudflare Pages platform (and integrate with Cloudflare's various other product offerings, such as KV, D1, R2, and Durable Objects).
This tool is a best-effort library implemented by the Cloudflare team and the community. As such, most, but not all, Next.js features are supported. See the Supported Versions and Features document for more details.
This section describes how to bundle and deploy a (new or existing) Next.js application to Cloudflare Pages, using @cloudflare/next-on-pages
.
To start using @cloudflare/next-on-pages
, you must have a Next.js project that you wish to deploy. If you already have one, change to its directory. Otherwise, you can use the create-next-app
command to start a new one.
npx create-next-app@latest my-next-app
cd my-next-app
Note on the Next.js version
We have confirmed support for the current version of Next.js at the time of writing, 13.4.2
. Although we'll endeavor to keep support for newer versions, we cannot guarantee that we'll always be up-to-date with the latest version. If you experience any problems with @cloudflare/next-on-pages
, you may wish to try pinning to 13.4.2
while we work on supporting any recent breaking changes.
For your application to run on Cloudflare Pages, it needs to opt in to use the Edge Runtime for routes containing server-side code (e.g. API Routes or pages that use getServerSideProps
). To do this, export a runtime
route segment config option from each file, specifying that it should use the Edge Runtime.
export const runtime = 'edge';
For more examples of this and for Next.js versions prior to v13.3.1, take a look at our examples document. Additionally, ensure that your application is not using any unsupported APIs or features.
To deploy your application to Cloudflare Pages, you need to install the @cloudflare/next-on-pages
package.
npm install -D @cloudflare/next-on-pages
Then you can deploy to Cloudflare Pages via the automatic Git integration. To do so, start by committing and pushing your application's code to a GitHub/GitLab repository.
Next, in the Cloudflare Dashboard, create a new Pages project:
- Navigate to the project creation pages (Your account Home > Workers & Pages > Create application > Pages > Connect to Git).
- Select the GitHub/GitLab repository you pushed your code to.
- Choose a project name and your production branch.
- Select Next.js as the Framework preset and provide the following options:
Option Value Build command npx @cloudflare/next-on-pages@1
Build output directory .vercel/output/static
- In the Environment variables (advanced) section, add a new variable named
NODE_VERSION
set to16
or greater. - Click on Save and Deploy to start the deployment (this first deployment won't be fully functional as the next step is also necessary).
- Go to the Pages project settings page (Settings > Functions > Compatibility Flags), add the
nodejs_compat
flag for both production and preview, and make sure that the Compatibility Date for both production and preview is set to at least2022-11-30
.
If you don't want to set up a Git repository, you can build your application (as indicated in Local Development) and publish it manually via the
wrangler pages publish
command instead (you'll still need to set thenodejs_compat
flag for your project in the Cloudflare dashboard).
Note: When deploying via the Git integration, for better compatibility with tools such as
yarn
andpnpm
we recommend using the Build system version 2 (that is the default so no action is required).
When developing a next-on-pages
application, this is the development workflow that Cloudflare recommends:
The standard development server provided by Next.js is the best available option for a fast and polished development experience. The next-dev
submodule makes it possible to use Next.js' standard development server while still having access to your Cloudflare bindings.
To ensure that your application is being built in a manner that is fully compatible with Cloudflare Pages, before deploying it, or whenever you are comfortable checking the correctness of the application during your development process, you will want to build and preview it locally using Cloudflare's workerd
JavaScript runtime.
Do this by running:
npx @cloudflare/next-on-pages
And preview your project by running:
npx wrangler pages dev .vercel/output/static
[!NOTE] The
wrangler pages dev
command needs to run the application using thenodejs_compat
compatibility flag. Thenodejs_compat
flag can be specified in either your project'swrangler.toml
file or provided to the command as an inline argument:--compatibility-flag=nodejs_compat
.
After you have previewed your application locally, you can deploy it to Cloudflare Pages (both via Direct Uploads or Git integration) and iterate over the process to make new changes.
Next.js applications built using @cloudflare/next-on-pages
get access to resources and information only available or relevant on the Cloudflare platform, such are:
-
Bindings (
env
), which allows you to take advantage of Cloudflare specific resources. -
Cloudflare properties (
cf
), object containing information about the request provided by Cloudflare’s global network. -
Lifecycle methods (
ctx
), methods to augment or control how the request is handled.
Such can be accessed by calling the getRequestContext
function in server only code.
For example:
import { getRequestContext } from '@cloudflare/next-on-pages';
// ...
const { env, cf, ctx } = getRequestContext();
Warning: The function cannot be called in code from components using the Pages router.
Note: In order to make the function work in development mode (using the standard Next.js dev server) use the
@cloudflare/next-on-pages/next-dev
submodule.
TypeScript Env Type: the
env
object returned bygetRequestContext
implements theCloudflareEnv
interface, add your binding types to such interface in order for get a correctly typedenv
object.
Note:
getRequestContext
throws an error if invoked when the request context is not available, if you prefer to receiveundefined
in such cases usegetOptionalRequestContext
instead, the latter is identical togetRequestContext
except from the fact that it returnsundefined
when the context is not available.
To see some examples on how to use Next.js features with @cloudflare/next-on-pages
, see the Examples document.
If you find yourself hitting some issues with @cloudflare/next-on-pages
please check out our official troubleshooting documentation.
For more information on the project please check out the README in the next-on-pages github repository.