Deploying Next.js

One tea shop, four places to run it

Deploying an app means putting it on a computer that visitors can reach, and keeping it running there. For a Next.js app, it starts the same way every time: next build turns your project into the files a server or a host needs. What runs those files is your choice. The Next.js docs name four ways:

• A Node.js server. Any computer that runs Node.js runs next start, Next.js's own server.
• A Docker container. The same server, packed with Node.js and your app into one box that runs the same way everywhere.
• A static export. No server of yours at all: next build writes plain files, and any web host sends them.
• A platform with an adapter. A hosting company runs the app for you. Its adapter is code that reshapes the build for its computers.

Here is the tea shop, built once and run the first way. It has the kinds of pages earlier lessons built: a home page with a photo, a menu that's cached for an hour, a cart that reads a cookie, and a proxy.ts. This example is a real Next.js 16.4.3 project. It was built with next build, started with next start, and what the server sent back was recorded. Click a file in the tree to read it.

1import Image from "next/image";2 3export default function Home() {4  return (5    <main>6      <h1>Tea shop</h1>7      <Image src="/green-tea.jpg" alt="A cup of green tea" width={480} height={320} />8      <p>Green tea: $4. Mint tea: $3.</p>9    </main>10  );11}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (5/5)  Finalizing page optimization ... Route (app)           Revalidate  Expire┌ ○ /├ ○ /_not-found├ ◐ /cart└ ○ /menu                     1h      1d ƒ Proxy (Middleware) ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ Ready

Open the Terminal tab. Under $ next build, the route table lists every route and how it's made: ○ / and ○ /menu are prerendered as static content, /menu with a Revalidate of 1h, ◐ /cart is a static shell with a part streamed in for each request, and ƒ Proxy (Middleware) says proxy.ts runs on the server. Under $ next start, the server says it's Ready on port 3000. Then the Network tab holds the five answers that one process sent: the pages, the cart made for the request, and a photo the image optimizer resized.

A Node.js server: next build, then next start

The first way is the one every project already has. Click package.json in the example's tree, one of the files marked create-next-app. Lines 7 and 8 are its build and start scripts: next build and next start. On any computer with Node.js, these three commands install, build and run the shop:

npm ci
npm run build
npm run start

Line 1 installs the exact packages the lockfile lists. Line 2 builds the app into the .next folder. Line 3 starts the server, which listens on port 3000 until you stop it (next start -p 8080 picks another port). The docs say this server supports every Next.js feature, and the recording shows several of them working in one process:

• Static pages. / came with Cache-Control: s-maxage=31536000: the page was made during the build, and a shared cache like a CDN may keep it for a year.
• Regenerated pages. app/menu/page.tsx is cached with "use cache" and cacheLife("hours"). Its answer says s-maxage=3600, stale-while-revalidate=82800: fresh for an hour, then served old while the server makes a new one in the background. That's Incremental Static Regeneration (Incremental Static Regeneration), and only a running server can do it.
• Streaming. /cart came with private, no-cache, no-store…, and its static shell first, with Loading your cart…, then the part that read the cookie (Partial Prerendering).
• Proxy. /teas has no page, yet it answered with the home page: proxy.ts rewrote the request on line 5 before any page ran (Proxy).
• Image Optimization. The last answer is the photo as WebP, 640 pixels wide, made by the server on request: X-Nextjs-Cache: MISS. That needs the sharp package, which npm ci installed with Next.js (Optimizing images).

Three more things come with running the server yourself. Environment variables that a page reads at request time are read when the request comes in, so one build can run with different values in each environment (Server-only code and environment variables). after() callbacks run once the answer has gone (Work after the response), so the server must be stopped gracefully: sent SIGTERM or SIGINT, then given time. The docs recommend 10 to 30 seconds, while it finishes the requests in flight and the pending callbacks. And the docs recommend a reverse proxy, like nginx, in front of the server rather than exposing it to the internet directly. Self-hosting sets all of that up.

Docker: the same server in a container

A server needs the right Node.js, the right packages and your built app, set up the same way on every computer that runs it. Docker packs all of that into one file:

• A Dockerfile is a list of steps that sets up the app, one after the other.
• docker build runs the steps and saves the result as an image: a snapshot of a small Linux system with Node.js, the packages and the built app inside.
• docker run starts a container from the image: a running copy, kept apart from the computer around it. One image can start many containers, on any computer or cloud that runs Docker, including orchestrators like Kubernetes.

This is the simplest Dockerfile that runs the tea shop. It isn't run on this page, and it isn't the one to ship:

FROM node:24.13.0-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "run", "start"]

Line 1 starts from an image with Node.js already in it, the version the official example uses. Line 2 makes /app the folder every later step works in. Lines 3 and 4 copy only the package files and install from the lockfile. Because they come before the rest of the code, Docker can reuse that step when only your code changes. Line 5 copies the rest of the project, and line 6 runs next build. Line 7 notes the port the server listens on, and line 8 is the command a container runs when it starts: npm run start, so next start. Two commands build the image and start one container:

docker build -t tea-shop .
docker run -p 3000:3000 tea-shop

Line 1 builds the image and names it tea-shop. Line 2 starts a container and connects the computer's port 3000 to the container's, so localhost:3000 reaches the shop. Inside, it's the same server as before, so the docs say a Docker deployment supports every feature too.

This image is bigger than it needs to be. It holds every package, the development tools included, and the whole project. The docs' official example uses output: "standalone", which makes next build write a small folder with only the files the server needs, and copies only that into the last stage of the image. Self-hosting builds that Dockerfile and records what the standalone folder holds. One more note from the docs: while you develop on a Mac or on Windows, run npm run dev directly on your computer rather than in Docker. It's faster there.

A static export: files on any web host

A static export leaves the server out. With output: "export" in next.config.ts, next build writes every page into a folder called out, as files. Any web server that sends files can host them: Amazon S3, nginx, Apache, GitHub Pages. The site you're reading is a Next.js app exported this way.

The price is everything that needs code to run when a request comes in. Try it with a smaller tea shop: a home page, and a cart. Each button below is one version, and each was built with real Next.js 16.4.3. Before you click, guess which ones build.

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  /* config options here */5  cacheComponents: true,6  partialPrefetching: true,7};8 9export default nextConfig;

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found└ ◐ /cart ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

Here is what each version shows:

1. For a server. The cart's CartItem reads the cookie on line 5 of app/cart/page.tsx, inside Suspense. The build prints ◐ /cart, and the server makes that part for each request.
2. Export, cookie on the server. The build stops on /cart: it couldn't be rendered statically because it used cookies(). In an export, every page must be made during the build, and no cookie exists then.
3. Export, cookie in the browser. The cart now reads the cookie in a Client Component, after the page has loaded: app/cart/cart-item.tsx, shown below. All four pages prerender. Then the export itself stops: Invariant: PPR cannot be enabled in export mode. In Next.js 16.4.3, a static export can't have Cache Components on.
4. Export, Cache Components off. With cacheComponents and partialPrefetching removed, the build prints ○ /cart and writes out: index.html, cart.html and 404.html, .txt files that hold each page's RSC payload for the router, and the JavaScript in _next/static. That folder is the whole site.

"use client";

import { useEffect, useState } from "react";

export default function CartItem() {
  const [tea, setTea] = useState<string | null>(null);
  useEffect(() => {
    setTea(document.cookie.match(/(?:^|; )cart=([^;]*)/)?.[1] ?? "");
  }, []);
  if (tea === null) return <p>Loading your cart…</p>;
  return <p>{tea ? `In your cart: ${tea}` : "Your cart is empty."}</p>;
}

Line 1 makes CartItem a Client Component (Client Components). Line 6 starts with null, so the page made during the build shows Loading your cart… on line 10. The Effect on lines 7 to 9 runs in the browser and reads the cookie from document.cookie, and line 11 shows it. Every visitor gets the same file; the browser fills in their own cart.

The static exports guide lists what isn't supported, because it needs a server: cookies and other request-time APIs, proxy.ts, rewrites, redirects and headers from next.config.ts, Incremental Static Regeneration, Image Optimization with the default loader, Draft Mode, Server Actions, intercepting routes, Route Handlers that read the request, and dynamic routes whose addresses generateStaticParams doesn't list (generateStaticParams). Static exports, in this stage, goes further: images, single-page apps, and what to do instead of each.

Platforms and adapters

A platform is a hosting company that runs your app on its computers, so you don't run servers yourself: Vercel, Netlify, Cloudflare, AWS Amplify, Firebase App Hosting, Deno Deploy and others. A platform often splits an app into parts: functions that run on demand, files on its CDN, rules that send each request to the right part. Something has to turn next build's output into those parts. That's an adapter.

Next.js has a public Build Adapters API for this, stable since Next.js 16.2. An adapter is a module named by adapterPath in next.config.ts, or by the NEXT_ADAPTER_PATH environment variable, which lets a platform set it for you:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  adapterPath: require.resolve("./my-adapter.js"),
};

export default nextConfig;

Line 6 names the adapter. It runs during next build and writes what its platform needs. The docs list two kinds of platform support:

• Verified adapters are open source and run Next.js's full compatibility test suite, and live under the Next.js GitHub organization. On the docs' Deploying page, those are Vercel's and Bun's. Vercel's adapter uses the same public API as everyone else's.
• Other platforms have their own Next.js integrations, not built on the public API and not verified, so what works varies: the docs name Appwrite Sites, AWS Amplify Hosting, Cloudflare, Deno Deploy, Firebase App Hosting and Netlify. Cloudflare and Netlify are working on verified adapters.

The docs separate two ideas. Functional fidelity means every feature works correctly; the test suite checks it. Performance fidelity means a feature is as fast as it can be, like a static shell served from a CDN close to the visitor. Platforms differ most in the second. Adapters and other platforms, later in this stage, looks at Vercel, Netlify, Cloudflare and OpenNext on AWS in turn.

Which features each way supports

The docs' Deploying page sums up the four ways in one table. Each row is one way:

Most features' pages in the docs end with a Platform support table with the same four columns. Here they are side by side. Image Optimization, Partial Prerendering, Server Actions and Route Handlers have no such table, so their rows come from the Deploying page and the self-hosting, static exports and PPR platform guides. Each row is one feature, and Platform-specific is the docs' word for "ask your platform":

The pattern is the one the playground showed: what needs code at request time works wherever next start runs, and not in a static export. Two details matter once there's more than one server, or something between the server and the visitor. The docs' Deploying to Platforms guide has a matrix for them. Each row is one feature: does it need responses to stream through, and should every instance of the server share one cache?

Streaming means the answer can arrive in pieces, like the cart's shell and then its cookie part. Nothing between the server and the browser may hold the pieces back until the end (Streaming). A host that does still works, the docs say, but the visitor waits for the whole page. A shared cache matters with several instances: without one, a page regenerated on one instance stays old on the others.

Partial Prerendering has one more option. next start sends a route's static shell and renders the rest in the same response. A CDN can also keep the shell close to visitors and ask the server for only the rest: the docs call this resuming, a POST with the header next-resume: 1 and the shell's saved state as its body. It's only faster, never required. Every feature in these tables works on a single next start.

Choosing a way for each project

Each row is one project, what it needs, and a way that fits it:

The first question is always the same: does anything need code to run when a request comes in? Sort these needs of the tea shop:

Common mix-ups

• "Next.js only runs on Vercel." No. The docs' first way is any computer with Node.js, and it supports every feature. Vercel is one platform, with one adapter, built on the same public API as the others.
• "Docker supports fewer features than a server." No. The container runs the same server. What it changes is how the server is packed and started.
• "A static export is a smaller build of the same app." No. It's a different kind of app: no code of yours runs when a request comes in. The playground's builds stopped on the cookie, and on Cache Components.
• "A static export can't have anything per visitor." It can, in the browser. The exported cart reads its cookie in a Client Component, after the file arrives.
• "Any platform supports everything." Not necessarily. The docs say support varies; verified adapters run the test suite, so you can see what works.
• "Features need a CDN or edge servers." No. The docs say one next start handles every feature correctly. A CDN, a shared cache and edge servers make it faster, and keep many instances in step.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

{
  "name": "my-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "16.4.3",
    "react": "19.3.0",
    "react-dom": "19.3.0"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "typescript": "^5"
  }
}

import { Suspense } from "react";
import { cookies } from "next/headers";

async function CartItem() {
  const tea = (await cookies()).get("cart")?.value;
  return <p>{tea ? `In your cart: ${tea}` : "Your cart is empty."}</p>;
}

export default function CartPage() {
  return (
    <main>
      <h1>Your cart</h1>
      <Suspense fallback={<p>Loading your cart…</p>}>
        <CartItem />
      </Suspense>
    </main>
  );
}

"use client";

import { useEffect, useState } from "react";

export default function CartItem() {
  const [tea, setTea] = useState<string | null>(null);
  useEffect(() => {
    setTea(document.cookie.match(/(?:^|; )cart=([^;]*)/)?.[1] ?? "");
  }, []);
  if (tea === null) return <p>Loading your cart…</p>;
  return <p>{tea ? `In your cart: ${tea}` : "Your cart is empty."}</p>;
}

import { cacheLife } from "next/cache";

export default async function MenuPage() {
  "use cache";
  cacheLife("hours");
  return (
    <main>
      <h1>Menu</h1>
      <p>Mint tea: $3. Green tea: $4.</p>
    </main>
  );
}

Check your understanding

For each question, ask what runs when a request comes in, and where.

Key takeaways

• You build once with next build. Then a Node.js server, a Docker container, a static host or a platform runs the result.
• next start supports every feature: static and regenerated pages, streaming, proxy.ts, the image optimizer, Cache Components and after(). A Docker container runs the same server.
• A static export writes out, a folder of files. Nothing of yours runs per request, so cookies, ISR, proxy, Server Actions and the default image loader don't work there. In Next.js 16.4.3, it also needs Cache Components off.
• A platform runs the build through its adapter (adapterPath). Verified adapters are open source and run Next.js's test suite; others vary.
• With several instances, the docs recommend a shared cache, and streaming must pass through every proxy. after() needs a server that's stopped gracefully.

Coming next: Self-hosting. It runs the shop on servers you manage: the standalone output, a production Dockerfile, a CDN in front, a cache shared by many instances, and deployments that don't break open pages.