Before you begin
Set the operating boundary first.
- A working application with repeatable local tests and a locked package manager.
- A Cloudflare account, Wrangler authentication, and a named production owner.
- A list of required bindings, secrets, data regions, and expected request paths.
- A low-risk smoke-test route and a rollback decision rule.
Step by step
Move from scope to a checked artifact.
Choose the deployment path deliberately
For a new Next.js application, start by checking vinext compatibility because Cloudflare lists vinext as its recommended path. For an existing OpenNext deployment, keep the adapter when migration has an unresolved compatibility gap. Use Pages only for a true static export.
- Checkpoint
- The repository records why vinext, OpenNext, or static Pages fits this application today.
- Artifact
- Deployment-path decision record
Define runtime and data boundaries
List which routes need server rendering or APIs and which can remain static. Add D1, R2, KV, Workers AI, Queues, or other bindings only when a validated feature requires them. Document what data crosses each boundary and which system owns deletion and recovery.
- Checkpoint
- Every binding has a named feature, data owner, and failure behavior.
- Artifact
- Runtime and binding map
Make the build reproducible
Pin the adapter and deployment tooling, generate binding types, and run type checks, tests, content validation, and the exact production build command. Keep secrets out of source control and distinguish preview configuration from production configuration.
- Checkpoint
- A clean checkout can produce the same deployment artifact without undocumented local state.
- Artifact
- Verified build and configuration inventory
Preview the production artifact
Run the built Worker locally or in a preview environment, then check status codes, redirects, metadata, static assets, authenticated boundaries, and any database migrations. Treat remote AI bindings as potentially billable even during local development.
- Checkpoint
- The exact production artifact passes a written route and binding matrix.
- Artifact
- Preview smoke-test record
Release a traceable version
Generate a public version marker from the commit, run a deployment dry-run, and deploy the immutable build. Record the commit, Worker version, deployment time, and operator. Avoid changing data schemas and application behavior in one unreviewed step.
- Checkpoint
- The public version marker resolves to the intended commit and the deployment provider reports a successful version.
- Artifact
- Production release record
Verify and keep rollback available
Repeat the route matrix against the public domain, including critical 200, redirect, 404, metadata, and API checks. Watch errors and user-visible regressions. Roll back when the release breaks a critical path or violates the prewritten acceptance boundary.
- Checkpoint
- Production matches the release record, or the previous known-good version is restored.
- Artifact
- Public verification and rollback decision
Deliverables
Keep the work reusable and inspectable.
- Deployment-path decision record
- Runtime, data, and binding map
- Repeatable production build command
- Preview route and binding matrix
- Commit-to-Worker release record
- Public smoke-test and rollback record
Decision boundaries
What this tutorial does not prove.
- Cloudflare labels vinext beta; verify its compatibility report before migrating an existing production application.
- OpenNext remains a documented maintenance path, but it should not be presented as Cloudflare’s default for a new application.
- D1, R2, Workers AI, and other services have separate limits, pricing, and data behavior that must be checked for the chosen plan.
- A successful deployment does not prove application correctness, security, data recovery, or model-output quality.
Source ledger
Check the current primary guidance.
- Cloudflare Workers: Next.js guide
Primary source for the current recommended vinext path, compatibility check, and Workers bindings.
- Cloudflare Workers: OpenNext adapter
Primary source for maintaining an existing OpenNext application and its supported Next.js features.
- Cloudflare D1 documentation
Primary source for D1 binding, data, and operational details.
- Cloudflare R2 documentation
Primary source for object-storage behavior, limits, and pricing links.