opennextjs-cloudflare CLI

The Cloudflare adapter provides a opennextjs-cloudflare CLI to develop, build, and deploy your application. You should not use wrangler commands directly unless documented otherwise or if you know what you are doing.

commands

opennextjs-cloudflare support multiple commands, invoked via opennextjs-cloudflare <command>.

The currently supported commands are build, populateCache, preview, deploy, upload, and migrate.

You can list the commands by invoking pnpm opennextjs-cloudflare and get help with a given command by invoking pnpm opennextjs-cloudflare <command> --help.

Most commands take command specific options (i.e. pnpm opennextjs-cloudflare build --skipNextBuild --noMinify) and also accept wrangler options (i.e. pnpm opennextjs-cloudflare build --config=/path/to/wrangler.jsonc --env=prod).

build command

It first builds the Next.js application by invoking the build script of the package.json - which typically execute next build. It then runs the Cloudflare specific build step to update the built files to run on the Cloudflare runtime.

populateCache command

It populates the configured Open Next cache components so that caching works at runtime. It can populate the local bindings (populateCache local) used during development on your local machine or the remote bindings (populateCache remote) used by the deployed application. Note that this command is implicitly called by the preview, deploy, and upload commands so there is no need to explicitly call populateCache when one of those is used.

Populating remote bindings when Workers are protected by Cloudflare Access

populateCache remote (also called implicitly by deploy and upload) temporarily deploys a helper Worker named open-next-cache-populate at open-next-cache-populate.<account>.workers.dev and uses it to write to your remote R2 bucket.

If your account's workers.dev subdomain — or a parent route on a custom domain — is protected by Cloudflare Access (opens in a new tab), the helper Worker is protected by the same policy and the upload fails with either:

Failed to send request to R2 worker: The operation was aborted due to timeout.

or a 403 Forbidden returned by the Access edge.

To let the adapter authenticate:

1. Open the existing Cloudflare Access application that already covers open-next-cache-populate.<account>.workers.dev — typically the wildcard application for *.<account>.workers.dev — and attach the policy described below to that application.

   ⚠️

   Creating a separate Access application scoped specifically to the open-next-cache-populate hostname has been observed to block the upload, even when kept alongside the existing wildcard application (see #1171 (opens in a new tab)). Prefer attaching the policy to the existing application that already protects the hostname.

2. Add a Service Auth policy to that application:

   • Set the policy Action to "Service Auth".
   • Add an Include rule for "Any Access Service Token", or for a specific service token.

3. Create the service token under Zero Trust → Access → Service Auth → Service Tokens, then expose its credentials to the environment that runs opennextjs-cloudflare:

   export CLOUDFLARE_ACCESS_CLIENT_ID=<id>
   export CLOUDFLARE_ACCESS_CLIENT_SECRET=<secret>

   Then run opennextjs-cloudflare populateCache remote (or deploy / upload). In CI, set the two values as secrets and expose them to the deploy step.

preview command

It starts by populating the local cache and then launches a local development server (via wrangler dev) so that you can preview the application locally.

deploy command

It starts by populating the remote cache and then deploys your application to Cloudflare (via wrangler deploy). The application will start serving as soon as it is deployed.

upload command

It starts by populating the remote cache and then uploads a version of your application to Cloudflare (via wrangler versions upload). Note that the application will not automatically be served on uploads. See Gradual deployments (opens in a new tab) to learn more about how to serve an uploaded version.

migrate command

Converts a standard Next.js project into an OpenNext-compatible one. This command automates the setup steps described in the Get Started guide, including:

• Installing required dependencies (@opennextjs/cloudflare and wrangler)
• Creating a wrangler.jsonc configuration file
• Creating an open-next.config.ts file
• Adding a .dev.vars file
• Updating the package.json scripts
• Adding static asset caching headers (public/_headers)
• Adding .open-next to .gitignore
• Setting up local development with initOpenNextCloudflareForDev() in your Next.js config

Additionally, the command creates an R2 bucket and configures it for caching.

Run the command in your existing Next.js project:

npx @opennextjs/cloudflare migrate