Running Next.js on Cloudflare Workers: what changes and what does not
A practical guide to the current Cloudflare Workers deployment path for Next.js, including what to expect from vinext, bindings, environment variables, and CI.
By AllFixAI engineering
The deployment target changed, the framework did not
Cloudflare Workers is now a first-class place to run a server-rendered Next.js application. The recommended route is vinext, a Vite-based implementation of the Next.js API surface that Cloudflare documents as the default way to run Next.js on Workers. Your app directory, route handlers, metadata, and server actions keep working; the compiler underneath changes.
That distinction matters when you plan a project. You are not rewriting your application. You are changing the build toolchain and adding a Worker configuration so the output runs in the Workers runtime.
Use the official tooling, not a hand-written config
The fastest way to waste a week is to copy a wrangler file from an old blog post. Cloudflare's guidance is deliberately simple: run the compatibility check, run the initializer, and let it generate the Vite and Wrangler configuration for the version of the tooling you actually installed.
- npx vinext check — scan your project and read the compatibility report before changing anything
- npx vinext init --platform=cloudflare — install dependencies and generate the Vite and Wrangler configuration
- npm run build:workers — produce the production build for the Workers target
- npx @vinext/cloudflare deploy — validate the setup, build, and deploy in one step
Bindings instead of process.env
On Workers, platform capabilities arrive as bindings: KV, D1, R2, Queues, Durable Objects, Workers AI, and Hyperdrive. Server code reads them from cloudflare:workers rather than from a Node process environment. Plain environment variables still work, but anything that expects a long-lived Node process — a pooled database socket held in module scope, for example — needs to be reconsidered.
For PostgreSQL the Workers-compatible pattern is a driver such as postgres.js used with prepared statements disabled, fronted by Hyperdrive so connection setup is pooled at the edge. That single change is what breaks most first deployments.
What to check before you commit to Workers
Run the compatibility check early and treat its output as a project risk list. Then look for the specific patterns that historically cause trouble.
- Native Node modules in server code, especially image processing and PDF generation
- Long-lived in-process caches and singletons that assume a persistent server
- Middleware that depends on Node-specific request APIs
- Local filesystem writes — Workers has no writable disk, so state belongs in KV, R2, or D1
- Anything that reads secrets at build time and expects them at runtime too
CI and deploy previews
Because the build is a Vite build, your pipeline stays ordinary: install, typecheck, lint, build. Cloudflare Workers Builds can run that pipeline directly from a GitHub push, which means pull requests get a preview and main deploys automatically once you trust it.
Keep the deploy command separated from the build command. The build produces the bundle; the deploy command is what ships it. Mixing them makes failures harder to attribute.
Next article