Preview deploys with OpenNEXT Cloudflare

I've been deploying personal projects to Cloudflare for its performance, pricing, and growing feature set. However, deploying Next.js has always been tricky depending on which features you need.

That's why I've been following Cloudflare's progress with the OpenNext initiative to make self-hosting Next.js easier. While they hit version 1 in May 2025 and recently released 1.5, it still feels like early days with plenty of rough edges.

One pain point is setting up preview deploys, which are currently in beta for Workers. It's actually straightforward but missing from the default template. To save you the hours I lost, you can replicate my setup in under 10 minutes.

Configuring Preview Deploys with opennextjs-cloudflare

Following the setup guide gives you a package.json like this:

"scripts": {
	"dev": "next dev --turbopack",
	"build": "next build",
	"start": "next start",
	"lint": "next lint",
	"deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
	"preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
	"cf-typegen": "wrangler types --env-interface CloudflareEnv ./cloudflare-env.d.ts"
},

The deploy script deploys the latest version, while preview runs your app locally via miniflare.

The opennextjs-cloudflare CLI supports an upload option missing from the template. This creates versions for gradual deployments.

Uploaded versions create previews when enabled in the worker's Domain & Routes settings. See the worker previews documentation for details.

To set this up: add a upload script, connect the worker to the GitHub repository, and configure the preview command in the UI.

First, add the upload command to package.json:

"upload": "opennextjs-cloudflare build && opennextjs-cloudflare upload",

Test locally with pnpm run upload. When complete, you'll get a Version Preview URL.

Next, connect the worker to your GitHub repository in the build settings. Replace the default Wrangler commands with those found in your package.json.

You'll need to add the Cloudflare application to your GitHub account. Once configured, PRs will generate preview deploys automatically.

See the setup and preview output in my public repo.

Using Environments and Preview Aliases

You can use environments with opennextjs-cloudflare by configuring them in your Wrangler file per the documentation and passing them like opennextjs-cloudflare deploy -e=staging. These support previews too—just use upload instead of deploy.

By default, uploads use the Git commit and branch name when in CI. To specify a custom alias, pass --preview-alias to opennextjs-cloudflare as you would with wrangler.