Cum Să Deployezi o Aplicație Next.js pe Cloudflare Workers în 2025

Cloudflare Workers este una dintre cele mai atractive platforme de deployment pentru Next.js în 2025. Cererile sunt gestionate de izolate V8 la edge-ul Cloudflare — cold start-uri de ordinul microsecundelor, fără management de server, și un tier gratuit care acoperă majoritatea proiectelor personale și produselor early-stage.

Dar deployarea Next.js pe Workers nu este același lucru cu deployarea pe Vercel sau un host Node.js. Există constrângeri reale, iar ignorarea lor îți va costa ore de debugging.

Acest ghid acoperă tot ce ai nevoie pentru a rula o aplicație Next.js 16 în producție pe Cloudflare Workers — inclusiv părțile pe care majoritatea tutorialelor le sar.

Adaptorul: @opennextjs/cloudflare

Next.js nu suportă oficial Cloudflare Workers ca target de deployment. Adaptorul comunitar @opennextjs/cloudflare umple acest gol. El convertește output-ul build-ului Next.js într-un format pe care Wrangler îl poate deploya.

Instalează-l împreună cu Wrangler:

npm install -D @opennextjs/cloudflare wrangler

Script-urile de build și deploy în package.json:

{
  "scripts": {
    "build": "next build",
    "preview": "opennextjs-cloudflare build && wrangler dev",
    "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy"
  }
}

wrangler.toml — esențialele

name = "my-next-app"
main = ".open-next/worker.js"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]

assets = { directory = ".open-next/assets", binding = "ASSETS" }

[vars]
NEXT_PUBLIC_SITE_URL = "https://my-app.example.com"

Flag-ul nodejs_compat este obligatoriu. Fără el, polyfill-urile pentru built-in-urile Node (ca crypto și Buffer) nu vor fi disponibile, și multe pachete npm vor eșua la runtime.

Constrângerea izolatului V8 — ce nu funcționează

Aici majoritatea deployment-urilor întâmpină probleme. Cloudflare Workers rulează în izolate V8, nu Node.js. Următoarele nu funcționează la runtime:

• fs, path, child_process — fără acces la filesystem
• net, http, https ca module Node — folosește Web Fetch API
• Node Buffer — folosește Uint8Array sau TextEncoder/TextDecoder
• Orice pachet care apelează require('fs') la runtime

Fraza cheie este la runtime. Poți folosi fs și path în codul de build-time (ca generateStaticParams, next.config.ts) deoarece acel cod rulează în Node.js în timpul build-ului. Doar codul de gestionare a cererilor rulează în Worker.

Citirea fișierelor locale în Worker

Dacă construiești un blog cu MDX sau fișiere markdown, abordarea standard cu fs.readFileSync(...) va eșua în producție. Modelul corect este să folosești generateStaticParams pentru a pre-construi toate paginile la build time:

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  // rulează în Node.js în timpul build-ului — fs funcționează bine
  const files = fs.readdirSync("content/blog/ro");
  return files.map((f) => ({ slug: f.replace(".mdx", "") }));
}

Paginile sunt apoi servite ca asset-uri statice din binding-ul de asset-uri al Workers. Fără acces la filesystem la request time.

Baza de date: folosește driver-ul HTTP, nu TCP

Dacă te conectezi la Postgres, nu poți folosi driver-ele standard bazate pe TCP (pg, postgres.js cu TCP, etc.) — Workers nu poate deschide conexiuni TCP persistente.

Folosește Neon cu driver-ul lor serverless HTTP:

npm install @neondatabase/serverless drizzle-orm

import { neon } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";

export function getDb(databaseUrl: string) {
  return drizzle(neon(databaseUrl));
}

Apelează getDb(env.DATABASE_URL) per cerere — nu memora instanța la nivel de modul, deoarece izolatele Workers nu partajează stare între cereri.

Tier-ul gratuit al Neon este generos, iar driver-ul HTTP este construit exact pentru acest tipar.

Variabile de mediu și secrete

Variabilele disponibile la build time (cu prefixul NEXT_PUBLIC_) merg în wrangler.toml sub [vars]. Valorile secrete — chei API, URL-uri de baze de date — nu ar trebui niciodată să fie în wrangler.toml. Folosește secretele Wrangler:

npx wrangler secret put DATABASE_URL
npx wrangler secret put STRIPE_SECRET_KEY
npx wrangler secret put RESEND_API_KEY

Pentru dezvoltare locală, creează un fișier .dev.vars (niciodată nu-l commit):

DATABASE_URL=postgresql://...
STRIPE_SECRET_KEY=sk_test_...

Wrangler îl preia automat pe .dev.vars când rulezi wrangler dev.

Probleme frecvente și cum le rezolvi

"Module not found: Can't resolve 'fs'" — Un pachet pe care îl importezi necesită fs la runtime. Înlocuiește pachetul cu o alternativă compatibilă cu browser-ul, sau mută utilizarea doar în codul de build-time.

"ReferenceError: Buffer is not defined" — Adaugă nodejs_compat la compatibility_flags în wrangler.toml, sau înlocuiește utilizarea Buffer cu Uint8Array.

Middleware-ul nu funcționează — Cloudflare Workers suportă edge middleware, dar funcția proxy.ts introdusă în versiunile recente Next.js este doar pentru Node.js. Folosește middleware.ts la rădăcina proiectului.

Asset-urile statice dau 404 după deploy — Verifică că binding-ul assets din wrangler.toml indică directorul corect (.open-next/assets).

Testarea build-ului Workers local

Înainte de deployment, testează întotdeauna cu runtime-ul Workers local:

npm run preview  # opennextjs-cloudflare build + wrangler dev

Aceasta rulează runtime-ul actual Workers local pe portul 8787. Este singura modalitate de a prinde probleme specifice Workers înainte ca ele să ajungă în producție.

---

Setup-ul complet descris aici — Next.js 16, Cloudflare Workers, Neon Postgres, Drizzle ORM, Stripe, Clerk și Resend — alimentează această platformă. Dacă vrei o implementare production-ready fără să petreci o săptămână pe infrastructură, pachetul DevOps Accelerator acoperă întregul pipeline de deployment ca un angajament cu scope fix.