Skip to content
Tutorials Center
My learning

Topics

Lesson 58 of 72 ยท Deployment and Production

Building and Deploying

Understand what next build produces, how to read its route table, when to use next start, static export or Vercel, and run a checklist before you go live.

Everything so far ran on your laptop with next dev, which compiles each page the first time you visit it and favors quick feedback over speed. Production is a different job. Before visitors arrive you build the app once: Next.js compiles the code for the server and the browser, type-checks the project, renders every page it can in advance, and writes the result into a folder. Then you run or upload that result.

This lesson explains what the build does, how to read the table it prints, and the three common ways to deploy: a Node.js server with next start, a static export you can host anywhere, and a managed platform such as Vercel. The next lesson goes deeper into self-hosting with Docker. Real builds cannot run on this site, so commands and configuration are read-only. The live examples are stand-ins written in Node.js: one prints a build-style route table from a list of pages, the other checks whether a project can be exported as static files.

What next build does

Compile Bundles server code and browser code.
Type-check Stops on type errors.
Prerender Renders static pages to HTML ahead of time.
Write .next Puts everything the server needs in one folder.

Build once, run many times.

1 / 2

What next build does

You run the build with one command:

Terminal
# read-only
npm run build   # runs "next build"

During the build Next.js:

  1. Compiles your code with the bundler (Turbopack is the default in recent versions) into separate bundles for the server and the browser, with code splitting and minification.
  2. Type-checks the project, so a type error fails the build (TypeScript, ESLint and Typed Routes). Linting is a separate step you run yourself in version 16.
  3. Renders static routes. Every page that does not depend on a request is executed once, right now, and its HTML and its RSC payload are saved. Pages using generateStaticParams are rendered once per listed parameter (Static Generation and generateStaticParams).
  4. Writes the output into the .next folder: server code, static assets with content-hashed file names, prerendered pages and a manifest that tells the server which route is which.

Because step 3 runs your code at build time, anything it needs (database access, environment variables, internet access to an API) must be available on the build machine. A page that fetches from a database that is unreachable during the build is the classic cause of "it works on my laptop but the pipeline fails".

The build is also where mistakes about static versus dynamic show up. Next.js prints a table of every route and how it will be served.

Reading the route table

The exact layout changes between versions, but the idea is stable: a tree of routes, each with a symbol.

TEXT
Route (app)
โ”Œ โ—‹ /
โ”œ โ—‹ /about
โ”œ โ— /blog/[slug]
โ”œ   โ”œ /blog/hello-world
โ”œ   โ”” /blog/second-post
โ”œ ฦ’ /dashboard
โ”” ฦ’ /search

โ—‹  (Static)   prerendered as static content
โ—  (SSG)      prerendered as static HTML (uses generateStaticParams)
ฦ’  (Dynamic)  server-rendered on demand
  • โ—‹ Static: rendered at build time, served as a file. Cheapest and fastest.
  • โ— SSG: also built ahead of time, one page per parameter value.
  • ฦ’ Dynamic: rendered on the server for each request (or cached after the first). It needs a running Node.js server.

If a page you expected to be static shows ฦ’, something in it reads the request: cookies(), headers(), searchParams, or an uncached fetch you marked dynamic. Static vs Dynamic Rendering explains how Next.js decides. With the Cache Components feature there is a further symbol for pages that have a static shell plus streamed dynamic parts (Partial Prerendering).

The stand-in below is not the real build. It takes a list of routes, each described by the features its code uses, applies simplified rules, and prints a table in the same style. Add a route or a feature and watch its symbol change.

Node.js A stand-in for the next build route table

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice /products/[id]. It has a dynamic segment but no generateStaticParams, so it is ฦ’: nothing tells the build which ids exist, so the page is rendered when someone asks for it.

Running the build: next start

The simplest production setup is a Node.js process:

Terminal
# read-only
npm run build
npm run start            # next start, serves on port 3000
npm run start -- -p 8080 # or: PORT=8080 npm run start

next start reads the .next folder and serves every kind of route: static files, dynamic pages, Route Handlers, Server Actions, the proxy file, image optimization and caching. It is a complete production server for one instance. Run it on a virtual machine, a PaaS such as Render or Railway, or inside a container. Put it behind a reverse proxy (nginx, Caddy, a cloud load balancer) that handles HTTPS, and use a process manager (systemd, PM2, or the container runtime) to restart it if it dies. Set NODE_ENV=production (next start does this itself) and make sure the build and the start use the same Node.js major version and the same environment variables, remembering that NEXT_PUBLIC_ values were fixed at build time (Environment Variables and Secrets).

A Node server is the most capable target: every feature works because the full runtime is there.

Static export

If your site is fully static (a marketing site, documentation, a blog without per-request logic), you can skip the server completely:

TypeScript
// next.config.ts (read-only)
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
  images: { unoptimized: true },
};

export default nextConfig;

next build now writes plain HTML, JavaScript, CSS and assets into an out/ folder. Upload it to any static host: an object store behind a CDN, GitHub Pages, a shared host. There is no Node.js process to run, so hosting is cheap and almost unbreakable.

The price is that anything needing a server is unavailable, and the build fails with an explanation if you use it. The main limits:

  • Dynamic routes need generateStaticParams listing every page, and unknown URLs are 404s.
  • No code that depends on the request: cookies(), headers(), reading searchParams on the server, the proxy file (middleware), redirects, rewrites or headers set in next.config.ts.
  • No Server Actions, and Route Handlers are only supported for GET handlers that can be evaluated at build time.
  • No incremental static regeneration or on-demand revalidation: content changes need a new build.
  • No default image optimization, since it needs a server; use unoptimized: true or a custom loader that points at an image service.

The checker below encodes these rules. Run it on the sample project, then edit the lists to see which features block an export. It is a teaching aid, not a replacement for the build's own errors.

Node.js Can this project be exported as static files?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The blog fails only because of the default image loader, which is a one-line fix. The shop fails for deeper reasons: it genuinely needs a server, so a Node.js deployment (or a platform) is the right target.

Vercel and other platforms

Vercel is the company behind Next.js, and deploying there needs almost no configuration: connect a Git repository, and each push builds and deploys. The platform turns your build output into the pieces it runs: static files on a global CDN, dynamic routes as serverless functions, image optimization and caching as built-in services, and a preview URL for every pull request. Environment variables are set in the dashboard, and a dashboard shows logs and performance. The trade-offs are cost at high traffic and depending on one vendor's infrastructure, which is why many teams choose to run Next.js themselves.

Other platforms exist because the output of next build is not magic. Some companies run next start in containers; others translate the build output to their own functions-and-CDN model using community tooling such as OpenNext. Recent Next.js versions also add an adapters API (still experimental): a hook that lets a hosting platform read a structured description of the build output, so each platform can map routes, caching and functions onto its own services without reverse-engineering the .next folder.

Target Best when Watch out for
next start on a server or container You want full features and full control You run HTTPS, scaling, restarts and caches yourself
Static export The site is fully static Many Next.js features are unavailable
Vercel You want the least operations work and PR previews Cost and platform dependence
Another platform with an adapter or OpenNext Your company standardizes on that cloud Check that your features (streaming, ISR, proxy) are supported

A pre-launch checklist

  • Run npm run build && npm run start locally and click through the important pages. It behaves differently from next dev.
  • Read the route table. Is every route the type you expect?
  • Set every environment variable on the host, including build-time ones such as NEXT_PUBLIC_ values.
  • Make sure the build machine can reach what static pages need (database, APIs).
  • Run database migrations as a separate pipeline step, not inside the build.
  • Add a simple health-check route and error reporting (Debugging and Error Handling).
  • Check HTTPS, redirects from www, and the robots and sitemap files.
  • After deploys that change content, purge the CDN cache if one sits in front.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the ฦ’ symbol next to a route in the build table mean?

    ฦ’ (Dynamic) routes depend on the request or have no known parameters at build time, so they are rendered by the server on demand.
  2. 2. Why does a page that reads from a database sometimes break only in the build pipeline?

    Static pages run your code at build time. If the data source is unreachable or the environment variables are missing there, the prerender fails.
  3. 3. Which feature prevents output: "export" from working?

    Server Actions need a running server. A static export has no server, so features like actions, cookies() and the proxy file are not available.
  4. 4. You change NEXT_PUBLIC_API_URL on the host and restart next start. Why do browsers still use the old value?

    NEXT_PUBLIC_ values become literal strings in the compiled bundles. Only a new build can change them.

Summary

  • next build compiles server and browser code, type-checks, prerenders static routes and writes the .next folder; it runs your code, so the build machine needs access to the data it uses.
  • The route table marks pages as โ—‹ static, โ— SSG or ฦ’ dynamic; an unexpected ฦ’ means the page reads the request.
  • next start serves every feature from one Node.js process; put a reverse proxy and a process manager around it.
  • output: "export" produces plain files for any static host, but gives up Server Actions, request-dependent code, the proxy file, redirects and rewrites, revalidation and default image optimization.
  • Vercel runs the build and serves the result with almost no setup; other platforms use containers, community tooling or the experimental adapters API.
  • Test the production build locally and run a checklist before launch.

Next: Self-Hosting and Docker