Deploying Next.js on Edge and Traditional Hosts

Next.js is flexible enough to run on a CDN-only bucket, a long-lived Node server, or an edge network—but each choice changes which features work, how you build, and what breaks at 3 a.m. Deployment is a product decision dressed as infrastructure.

This post maps deployment paths for teams shipping marketing plus app surfaces. Read it alongside static export vs SSR for rendering tradeoffs, shipping fast with performance budgets for what to measure after deploy, and env and secrets for build-time versus runtime configuration.

Know your output mode first

Before picking a host, decide what the build produces:

• Static export — HTML/CSS/JS artifacts; no Node at the edge. See output: 'export' and the dedicated comparison in static export vs SSR.
• Node server — next start or output: 'standalone' for container or VM hosting.
• Platform-managed — Vercel, Netlify, Cloudflare Pages with Next.js adapters; features vary by vendor.

Mismatch causes production surprises: image optimization, middleware, and dynamic routes behave differently per mode.

Static export on traditional static hosts

Upload build output to S3 + CloudFront, Azure Static Web Apps, GitHub Pages, or any static file host. CI runs next build with export enabled; invalidation refreshes CDN caches.

Pros: low cost, simple blast radius, great for marketing and docs. Cons: no server components that need per-request secrets, no ISR unless your host emulates it (often they do not).

Pair static marketing with an API on Docker or serverless elsewhere—subdomain split keeps concerns clear.

Node on VMs and containers

Self-hosted Node suits teams with compliance needs, existing Kubernetes, or predictable traffic. Use output: 'standalone' to trim node_modules in the image per Next.js standalone output.

Run behind a reverse proxy (nginx, Caddy) for TLS termination and request size limits. Configure health checks on a lightweight route. Graceful shutdown on deploy: handle SIGTERM, finish in-flight requests within platform timeout.

Horizontal scale means shared session state or sticky sessions if you use in-memory caches—prefer Redis for sessions as in auth session patterns.

Edge runtimes and middleware

Edge deployments run a subset of Node APIs closer to users—useful for geolocation redirects, A/B assignment, or auth gating at the boundary. Next.js middleware runs on the edge on supported platforms; verify which APIs your edge runtime exposes (no raw TCP, limited file system).

Keep middleware fast and deterministic; heavy work belongs in regional Node or background jobs.

Platform hosts (managed Next.js)

Managed platforms integrate git deploys, preview URLs, and automatic SSL. Read their Next.js compatibility matrix: App Router version, ISR, edge functions, and build cache limits.

Preview deployments need isolated env secrets—never wire preview to production databases. Cost-aware cloud choices applies when preview build minutes accumulate.

Environment variables per host

Static export bakes NEXT_PUBLIC_* at build time per environment pipeline—staging and prod builds are separate artifacts. Node servers can read secrets at runtime; prefer that for database URLs.

Document which vars each host injects; drift between preview and prod causes “works in preview” bugs.

Images, fonts, and assets

next/image optimization may require the image loader your host provides or custom loader URLs on static export. Self-host review image optimization docs for unoptimized or external loader patterns.

Font subsetting and next/font reduce layout shift; confirm font files ship in the artifact for static hosts.

CI/CD shape

Typical pipeline: install, lint, test, next build, deploy artifact or image. Cache dependencies and .next/cache when the platform allows. Tag releases; roll back by redeploying previous artifact digest.

For containers, promote the same image from staging to prod with only env changes—see observability starter kit for release markers in logs.

CDN and caching headers

Static assets with hashed filenames cache aggressively (immutable). HTML may need shorter TTL or stale-while-revalidate depending on how often marketing updates. API responses should send explicit Cache-Control—do not cache authenticated JSON at shared CDNs.

Staging fidelity

Staging should mirror production’s output mode even if it runs on smaller instances—a static-export prod with SSR staging hides broken getServerSideProps assumptions until launch week. Match Node versions and major dependency locks between environments.

Multi-region and latency

Edge helps first-byte latency for middleware and static assets; dynamic SSR still hits origin unless you replicate databases—a hard problem. Most early SaaS ships single-region API with global CDN for static marketing; expand when contracts or latency SLOs demand it.

When to split apps

If marketing is static and product is SSR, two deployables reduce coupling: www on CDN, app on Node. Shared design tokens and component libraries keep UX coherent; shared monorepo optional.

DNS, TLS, and custom domains

Point apex and www consistently; avoid duplicate hosts without redirects. Automated TLS (Let’s Encrypt via your host or cert-manager in Kubernetes) should renew before expiry—alert on certificate lifetime under thirty days.

For multi-tenant subdomains (customer.app.com), document how wildcard certs or per-tenant DNS interact with your auth cookies.

Review Next.js deployment documentation when upgrading major versions—host adapters and default output modes change more often than marketing pages admit.

Database and serverless SSR

Serverless Next.js SSR that opens new database connections per invocation can exhaust Postgres max_connections under load. Use poolers (PgBouncer, Neon serverless driver patterns) and keep queries short. This is deployment architecture, not ORM tuning alone.

Failure modes to rehearse

• Build succeeds but server routes 404 because export mode excluded them
• Middleware infinite redirect on auth cookie edge cases
• OOM on small containers during build—raise CI memory or build on larger runners
• Cold starts on serverless SSR affecting p95—consider minimum instances or static where possible

Closing

Deploying Next.js well means choosing static export, Node, or edge based on freshness, secrets, and budget—not defaulting to whatever the first tutorial used. Document output mode, env injection, and rollback for each environment; split marketing static from app dynamic when hybrids simplify operations. The framework supports many hosts—your job is to align product requirements with what each host actually runs after next build.

Keep a one-page deploy matrix in the repo: environment, host, output mode, branch, and rollback command. Future you during an outage will not remember whether preview uses export or standalone.

Smoke tests after deploy should hit one static page, one dynamic route, and one API mutation in staging before promoting to production—automate the trio in CI where possible so human forgetfulness is not the release gate.

Document maximum request body size and timeout at the reverse proxy; Next.js defaults interact with platform limits, and upload features fail mysteriously when nginx allows 1MB while the app allows 10MB.

If you use cost-aware hosting splits, tag deploy workflows with environment names so CI analytics show which pipelines consume the most minutes—often preview builds, not production.

Regional edge deploys may require you to pin compatible runtime versions across locations—validate in staging that middleware and edge bundles behave identically, not only the Node server in one region.

Keep previous production artifacts or images addressable for at least one release cycle so rollback is a pointer change, not an emergency rebuild from a branch you already deleted.