The Build, and What It Produces

npm run build

// 1. Compile          TypeScript and JSX -> JavaScript (SWC)
// 2. Lint and typecheck (unless disabled)
// 3. Bundle           client chunks, per route
// 4. Prerender        run every static page and write HTML
// 5. Optimise         minify, tree-shake, generate the manifests

// Phase 4 is the one that surprises people: your page code RUNS at
// build time. So a build fails if a static page:
//   queries a database that is not reachable from CI
//   reads an environment variable that is not set in CI
//   calls an API that is down
// "Error occurred prerendering page /problems" means your code threw
// during the build, not that the route is misconfigured.

// Skipping checks in the build is a trap worth naming:
// next.config.js
typescript: { ignoreBuildErrors: true }     // do not
eslint: { ignoreDuringBuilds: true }        // do not
// Both hide the failure until runtime. Run tsc and eslint as separate
// CI steps if the build is slow, but do not silence them.

Route (app)                          Size     First Load JS
┌ ○ /                                5.2 kB          98 kB
├ ● /learn/[topic]/[concept]         1.8 kB          95 kB
├   └ [+199 more paths]
├ ƒ /dashboard                       3.1 kB          96 kB
+ First Load JS shared by all                        89.1 kB

// 1. The SYMBOL — ○ static, ● SSG, ƒ dynamic. A route that moved from
//    ○ to ƒ is the most common silent regression.
// 2. FIRST LOAD JS — what a visitor downloads before the page is
//    interactive. Under ~100kB shared is healthy; watch the trend.
// 3. SHARED BY ALL — a jump here means something entered the common
//    chunk, usually a library imported from a layout.
// 4. PATH COUNT — a generateStaticParams returning far more than
//    expected lengthens builds and inflates the deployment.

// Diff it between deploys. Some teams fail CI on a size increase:
npx bundlesize
// or compare .next/analyze output.

// Local build times are misleading — CI is usually slower and colder.
// If builds hurt, look at the number of prerendered paths first.

.next/
  static/            hashed JS, CSS and media — CDN-cacheable forever
  server/            server code, and the prerendered HTML/RSC payloads
  cache/             the build and data caches — restore this in CI
  BUILD_ID           identifies the build; hashed filenames derive from it

// Cache .next/cache in CI or every build recompiles from scratch:
- uses: actions/cache@v4
  with:
    path: .next/cache
    key: next-${{ hashFiles('package-lock.json') }}-${{ github.sha }}

// output: 'standalone' — a minimal self-contained server, for Docker
module.exports = { output: 'standalone' }
// .next/standalone contains a server.js and only the node_modules it
// actually needs. It turns a 1GB image into roughly 150MB.

// output: 'export' — a purely static site, no Node at all
module.exports = { output: 'export' }
// Gives up: server components with dynamic data, server actions,
// route handlers, ISR, middleware and next/image optimisation.
// Right for documentation; wrong for an application.

// A hashed filename is why a new deploy invalidates the client cache
// cleanly — and also why an OLD client asking for a removed chunk
// 404s, which is the post-deploy failure covered in the React track.