Inside next build

One build of the tea shop, from start to finish

next build turns your project into an app that next start can serve. Earlier lessons read what it prints. Its source shows how it works: the code in Next.js that runs when you type the command, and the files it leaves behind. The source quoted is Next.js 16.4.3's, from GitHub at the tag v16.4.3.

The running example is the tea shop: a home page, a page for each tea at /teas/[id] with an Add to cart button, and a cart page that reads a cookie. Here it is, built with next build. The Terminal tab opens first. Under what the build printed, it lists what the .next folder held afterwards: each file up to two levels down, with deeper files added up into their folder.

1import { notFound } from "next/navigation";2import { AddToCart } from "../../add-to-cart";3import { findTea, teas } from "../../teas";4 5export function generateStaticParams() {6  return teas.map((tea) => ({ id: tea.id }));7}8 9export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {10  const { id } = await params;11  const tea = findTea(id);12  if (!tea) notFound();13  return (14    <main>15      <h1>{tea.name}</h1>16      <p>${tea.price}</p>17      <AddToCart id={tea.id} />18    </main>19  );20}

$ 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 (7/7)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ◐ /cart└   /teas/[id]  ├ ◐ /teas/[id]  ├ ○ /teas/green  └ ○ /teas/mint ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content # What .next holds: 228 files, 29.0 MB (deeper folders added up).next/BUILD_ID  21 bytes.next/app-path-routes-manifest.json  158 bytes.next/build-manifest.json  2.3 kB.next/cache/.previewinfo  262 bytes.next/cache/.rscinfo  102 bytes.next/cache/.tsbuildinfo  121.5 kB.next/cache/turbopack/  23.2 MB, 20 files.next/diagnostics/build-diagnostics.json  93 bytes.next/diagnostics/framework.json  37 bytes.next/diagnostics/route-bundle-stats.json  1.8 kB.next/export-marker.json  111 bytes.next/fallback-build-manifest.json  366 bytes.next/images-manifest.json  1.2 kB.next/next-minimal-server.js.nft.json  9.8 kB.next/next-server.js.nft.json  91.1 kB.next/package.json  20 bytes.next/prerender-manifest.json  9.5 kB.next/required-server-files.js  10.8 kB.next/required-server-files.json  10.8 kB.next/routes-manifest.json  2.3 kB.next/server/app-paths-manifest.json  212 bytes.next/server/app/  229.5 kB, 85 files.next/server/chunks/  4.7 MB, 70 files.next/server/functions-config-manifest.json  37 bytes.next/server/interception-route-rewrite-manifest.js  48 bytes.next/server/middleware-build-manifest.js  2.3 kB.next/server/middleware-manifest.json  83 bytes.next/server/next-font-manifest.js  135 bytes.next/server/next-font-manifest.json  94 bytes.next/server/pages-manifest.json  58 bytes.next/server/pages/  17.1 kB, 2 files.next/server/prefetch-hints.json  1.1 kB.next/server/preview-props.json  250 bytes.next/server/server-reference-manifest.js  422 bytes.next/server/server-reference-manifest.json  352 bytes.next/static/Ck2PLfmuLay5_FTZYdHZb/  417 bytes, 3 files.next/static/chunks/  593.0 kB, 10 files.next/trace  6.6 kB.next/trace-build  1.8 kB.next/turbopack  0 bytes.next/types/cache-life.d.ts  4.6 kB.next/types/root-params.d.ts  101 bytes.next/types/routes.d.ts  1.5 kB.next/types/validator.ts  5.3 kB

Each line the build printed is one step. Creating an optimized production build is the compile. Running TypeScript is the type check. Collecting page data asks each route what it is. Generating static pages (7/7) made 7 pages ahead of time. The route table comes last. The output above has no times, no worker counts and no page counter (the line a terminal draws over itself): they change from run to run, so they were removed.

The folder listing is the other half of the story. A manifest is a file that lists what the build made, so the server doesn't have to work it out again: routes-manifest.json, prerender-manifest.json and others. server/ holds the code that runs on the server, static/ the files the browser downloads, and cache/ what the next build can reuse. The steps, in order:

The steps of next build, in build/index.ts

next build starts in the CLI, which calls one function: build, at line 1116 of build/index.ts. The file is almost 5,000 lines long, but the function reads from top to bottom, one step after another. Each step is wrapped in a span: a named piece of work with a start time and a length, made by nextBuildSpan.traceChild("…"). Next.js writes the spans into a file you can open yourself: .next/trace. These are the tea shop's recorded top-level spans, the ones directly under next-build, in the order they started:

generate-buildid
load-custom-routes
create-dist-dir
clean
discover-routes
create-root-mapping
generate-route-types
public-dir-conflict-check
generate-routes-manifest
run-turbopack
turbopack-write-entrypoints
turbopack-module-graph
turbopack-emit
turbopack-persistence
run-typescript
generate-required-server-files
static-check
write-routes-manifest
static-generation
next-export
print-tree-view
write-route-bundle-stats
telemetry-flush

Each name is a traceChild in build/index.ts, so you can search the file for it. Loading the settings is an earlier phase that the file doesn't show: its spans, load-dotenv and load-next-config, end before Next.js knows where .next is, and the trace writer drops a span when it doesn't know that yet (to-json.ts, lines 186 to 190), and build only tells it after the config is loaded, at lines 1245 and 1246. The settings phase first, then the spans in order, give the steps of the picture above:

1. Settings, before the trace starts. load-dotenv reads the .env files, then loadConfig reads next.config.ts (lines 1170 to 1195). Then, in the trace, generate-buildid makes up this build's id, and load-custom-routes reads the redirects, rewrites and headers.
2. A clean folder. clean deletes .next, but keeps cache, dev, diagnostics, lock and trace (lines 1379 to 1388).
3. Routes. discover-routes walks the app folder for page and route files. generate-route-types writes the types behind PageProps<"/teas/[id]"> into .next/types, and generate-routes-manifest builds the routes manifest in memory, before anything is compiled (lines 1784 to 1800).
4. Compile. run-turbopack and the four turbopack- spans under it: Turbopack, Next.js's bundler, compiles every route.
5. Types. run-typescript.
6. Page data. generate-required-server-files writes the server's settings, then static-check asks the worker pool about each route.
7. Prerender. static-generation, and next-export inside it.
8. Manifests and the table. write-routes-manifest appears twice, because the build writes that file, then updates it after prerendering. print-tree-view prints the route table.

The compile is one call. This is how build/index.ts makes it, shortened:

Log.info('Creating an optimized production build ...')
…
if (!isGenerateMode) {
  if (bundler === Bundler.Turbopack) {
    const {
      duration: compilerDuration,
      shutdownPromise: p,
      warnings,
      ...rest
    } = await turbopackBuild(telemetry)
    …
    const durationString = durationToString(compilerDuration)
    Log.event(`Compiled successfully in ${durationString}`)

Line 1 prints Creating an optimized production build .... Line 4 checks the bundler: Turbopack, unless you ran next build --webpack. Line 10 hands the whole compile to turbopackBuild, in turbopack-build/impl.ts, which starts Turbopack's Rust code and asks it to write every route to disk: the server's code, the browser's chunks, and a small manifest for each route. Line 13 prints ✓ Compiled successfully, with the time the recording leaves out. What Turbopack does inside that call is in SWC and Turbopack.

And this is the type check, right after it:

// For app directory, we run type checking after build.
if (appDir && !isCompileMode && !isGenerateMode) {
  await updateBuildDiagnostics({
    buildStage: 'type-checking',
  })
  await startTypeChecking(typeCheckingOptions)
  traceMemoryUsage('Finished type checking', nextBuildSpan)
}

Line 1 says it plainly: with an app folder, types are checked after the compile. Line 6 runs TypeScript. Turbopack only removes types from your code; it never checks them. So a type error doesn't stop the compile, and the build stops one step later. Each row of this table is one step, what it does, and what it leaves in .next:

The order shows best when a build fails. Each version below breaks one thing in the tea shop, and each was built with real Next.js. Before you click, guess which line each build stops at.

1import { notFound } from "next/navigation";2import { AddToCart } from "../../add-to-cart";3import { findTea, teas } from "../../teas";4 5export function generateStaticParams() {6  return teas.map((tea) => ({ id: tea.id }));7}8 9export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {10  const { id } = await params;11  const tea = findTea(id);12  if (!tea) notFound();13  return (14    <main>15      <h1>{tea.name}</h1>16      <p>${tea.price}</p>17      <AddToCart id={tea.id} />18    </main>19  );20}

$ 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 (7/7)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ◐ /cart└   /teas/[id]  ├ ◐ /teas/[id]  ├ ○ /teas/green  └ ○ /teas/mint ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content # What .next holds: 228 files, 29.0 MB (deeper folders added up).next/BUILD_ID  21 bytes.next/app-path-routes-manifest.json  158 bytes.next/build-manifest.json  2.3 kB.next/cache/.previewinfo  262 bytes.next/cache/.rscinfo  102 bytes.next/cache/.tsbuildinfo  121.5 kB.next/cache/turbopack/  23.2 MB, 20 files.next/diagnostics/build-diagnostics.json  93 bytes.next/diagnostics/framework.json  37 bytes.next/diagnostics/route-bundle-stats.json  1.8 kB.next/export-marker.json  111 bytes.next/fallback-build-manifest.json  366 bytes.next/images-manifest.json  1.2 kB.next/next-minimal-server.js.nft.json  9.8 kB.next/next-server.js.nft.json  91.1 kB.next/package.json  20 bytes.next/prerender-manifest.json  9.5 kB.next/required-server-files.js  10.8 kB.next/required-server-files.json  10.8 kB.next/routes-manifest.json  2.3 kB.next/server/app-paths-manifest.json  212 bytes.next/server/app/  229.5 kB, 85 files.next/server/chunks/  4.7 MB, 70 files.next/server/functions-config-manifest.json  37 bytes.next/server/interception-route-rewrite-manifest.js  48 bytes.next/server/middleware-build-manifest.js  2.3 kB.next/server/middleware-manifest.json  83 bytes.next/server/next-font-manifest.js  135 bytes.next/server/next-font-manifest.json  94 bytes.next/server/pages-manifest.json  58 bytes.next/server/pages/  17.1 kB, 2 files.next/server/prefetch-hints.json  1.1 kB.next/server/preview-props.json  250 bytes.next/server/server-reference-manifest.js  422 bytes.next/server/server-reference-manifest.json  352 bytes.next/static/Ck2PLfmuLay5_FTZYdHZb/  417 bytes, 3 files.next/static/chunks/  593.0 kB, 10 files.next/trace  6.6 kB.next/trace-build  1.8 kB.next/turbopack  0 bytes.next/types/cache-life.d.ts  4.6 kB.next/types/root-params.d.ts  101 bytes.next/types/routes.d.ts  1.5 kB.next/types/validator.ts  5.3 kB

A missing file stops the compile: Turbopack can't follow the import, and nothing after it runs. The type error compiles, then stops at Running TypeScript, with (17,18): line 17, column 18. The page that throws gets through both, and fails while a worker prerenders /teas/oolong. Each failure stops at the first step that can see it.

Prerendering in a worker pool

A process is a program that's running, with its own memory. next build is one Node.js process, the main process. Rendering many pages in it, one after another, would leave the computer's other cores idle. So after the compile, the build starts more Node.js processes, called workers, and sends them pages to render. The group of workers is a pool.

createStaticWorker, at lines 1010 to 1057 of build/index.ts, makes the pool. Each worker loads build/worker.ts, which offers four functions to the main process: hasCustomGetInitialProps, isPageStatic, getDefinedNamedExports and exportPages. The first three answer Collecting page data. exportPages, from export/worker.ts, prerenders. The pool is built on jest-worker, a library that runs a file in several processes and spreads calls across them. Next.js uses child processes unless you turn on experimental.workerThreads (lib/worker.ts, lines 163 to 172).

How many workers

The build sizes the pool once, after the type check: getNumberOfWorkers(config, totalPageCount), at lines 2256 to 2261. The setting that counts is experimental.cpus, whose default is the computer's cores minus one (config-shared.ts, lines 2422 to 2426). Then the pool gets at most one worker more than there are routes: an app with 5 routes never starts more than 6 workers, however many cores the computer has.

How the pages are split

For prerendering, the paths are split into batches, and each batch goes to one worker: exportPagesInBatches, at lines 692 to 745 of export/index.ts. The number of batches is the paths divided by 25, rounded up (staticGenerationMinPagesPerWorker), capped at the number of workers (lines 706 to 709). Then the paths are cut, in order, into slices of the same size, one per batch, the last one sometimes shorter (lines 712 to 722). So 25 is the target that picks how many batches there are, not the size of a batch: 7 paths make 1 batch, 26 paths make 2 batches of 13, and 120 paths with 5 workers make 5 batches of 24. Inside a worker, exportPages renders up to 8 paths at a time (staticGenerationMaxConcurrency, export/worker.ts, lines 432 and 433). The tea shop on a computer with 8 cores:

Move the sliders. Start with the tea shop, then give it 120 paths: when does a second worker get a batch? Then give it 2 routes: what happens to the pool?

function getNumberOfWorkers(config: NextConfigComplete, maxTasks?: number) {
  let workers: number
  …
  } else if (config.experimental.cpus) {
    workers = config.experimental.cpus
  }
  …
  // Cap workers to one more than the number of tasks.
  // Tasks can be passed to avoid over-allocating workers.
  if (maxTasks !== undefined && maxTasks > 0) {
    workers = Math.min(workers, maxTasks + 1)
  }

  return Math.max(workers, 1)
}

const minPageCountPerBatch =
  nextConfig.experimental.staticGenerationMinPagesPerWorker ?? 25

// Calculate the number of workers needed to ensure each batch has at least
// minPageCountPerBatch pages.
const numWorkers = Math.min(
  options.numWorkers,
  Math.ceil(exportPaths.length / minPageCountPerBatch)
)

// Calculate the page count per batch based on the number of workers.
const pageCountPerBatch = Math.ceil(exportPaths.length / numWorkers)

With 7 paths, the pool has 6 workers, but only one batch. At 26 paths, a second batch appears. With 2 routes, the pool shrinks to 3, however many cores there are. Your terminal prints the pool's size, like Generating static pages using 6 workers, even when one batch is all there is. Both limits, 25 and 8, can be changed in next.config.ts; they're experimental settings, so they can change in any release.

When a page fails

Open the playground above again and pick A page that throws. The last line of the Terminal says ⨯ Next.js build worker exited with code: 1 and signal: null. That's the pool at work. When /teas/oolong threw, exportPages printed the error and ended its process, because experimental.prerenderEarlyExit is on by default (export/worker.ts, lines 526 to 531). The main process watches each worker; when one exits with an error, it prints that line and exits with the same code (lib/worker.ts, lines 172 to 185). One failed page fails the whole build, so a broken page never reaches next start.

The manifests, and what reads them

After the build, next start knows nothing about your app folder. Everything it needs, the build wrote down. Turbopack writes a small manifest for each route while it compiles, and TurbopackManifestLoader merges them into the files at the top of .next (turbopack-build/impl.ts, lines 227 to 295). build/index.ts writes the rest: routes-manifest.json (line 3076), BUILD_ID (line 3098) and prerender-manifest.json (line 4619).

Two different pieces of code read them, at two different times:

• At startup, for route matching. The router server decides which route a request is for. When it starts, it calls setupFsCheck (router-server.ts, line 177), which reads the routes manifest, the two app manifests, the middleware manifest and the pages manifest once (filesystem.ts, lines 348 to 396).
• Per route, when its module handles a request. A route's compiled module calls loadManifests each time it prepares a request (route-module.ts, lines 873 to 877). That reads the routes, prerender, build and server reference manifests, the page's client reference manifest and required-server-files.json (lines 341 to 466). In production each file is read once and kept (shouldCache: !this.isDev).

Pick a manifest below and read the tea shop's:

{
  "dynamicRoutes": [
    {
      "page": "/teas/[id]",
      "regex": "^/teas/([^/]+?)(?:/)?$",
      "routeKeys": {
        "nxtPid": "nxtPid"
      },
      "namedRegex": "^/teas/(?<nxtPid>[^/]+?)(?:/)?$"
    }
  ],
  "staticRoutes": [
    "/",
    "/_global-error",
    "/_not-found",
    "/cart"
  ]
}

Read app-path-routes-manifest.json and app-paths-manifest.json side by side: one entry, /teas/[id]/page, leads to an address in one file and to a file of code in the other. The server reference manifest has the shop's one Server Action, addToCart, under an id the build made up. Its workers name app/teas/[id]/page, the route whose server code can run it. (Here "worker" means a route's server code, not a build worker.) How those ids are made, and the client reference manifests beside each page, are taught in 'use client' and 'use server' under the hood.

Each row is one manifest, what it says, and what reads it:

The .next folder you can read yourself

Go back to the tea shop's Terminal tab at the top and read the listing under the route table. The build's id is a random string, so static/ has a folder named after it; the paths below call it <buildId>. The sizes are this machine's, from one build. In the listing:

• The manifests at the top: routes-manifest.json, prerender-manifest.json, build-manifest.json, app-path-routes-manifest.json, required-server-files.json, and BUILD_ID, a file holding only the id.
• server/: the server's manifests, then server/app/, with each route's compiled code (page.js) and the pages made during the build (.html, .rsc, .meta and segment files; Partial Prerendering reads them), and server/chunks/, the code the routes share.
• static/: the browser's files. /_next/static/… in the HTML points here. static/chunks/ holds the JavaScript (Shrinking the JavaScript bundle measures it), and static/<buildId>/ three small files for the browser's router.
• cache/: what the next build may reuse. cache/turbopack/ is Turbopack's filesystem cache, and cache/.tsbuildinfo is TypeScript's notes from the type check. The clean step keeps this folder.
• types/: the route types from generate-route-types.
• trace and trace-build: the spans you read above. trace-build keeps only the main ones, from a fixed list (to-json-build.ts).
• turbopack, an empty file (0 bytes): a sign that Turbopack made this build (impl.ts, lines 172 and 173).
• package.json, 20 bytes: {"type": "commonjs"}, so Node.js loads the server's .js files the same way even when your own package.json says "type": "module" (impl.ts, lines 179 to 182).
• next-server.js.nft.json and next-minimal-server.js.nft.json: traces of the server's own files. output: "standalone" uses them.

None of these files needs Next.js to read. They're JSON or text, and your editor opens them. When a build surprises you, the answer is often written in .next.

Output file tracing and standalone

Your project's node_modules holds hundreds of packages: the build tools, TypeScript, the types. The server needs only some of them. Output file tracing finds which: it reads a route's compiled code without running it, follows every import, require and file read it can identify that way, and writes the files that may be needed into a .nft.json file beside it (NFT stands for Node File Trace). In a Turbopack build, Turbopack writes these files itself while it writes the routes (crates/next-api/src/nft_json.rs); build/index.ts runs its older tracer, collect-build-traces, only for webpack builds (lines 3017 to 3021). This is the tea page's trace, from the build below:

../../../../../node_modules/@swc/helpers/cjs/_interop_require_default.cjs
../../../../../node_modules/@swc/helpers/esm/_interop_require_default.js
../../../../../node_modules/@swc/helpers/package.json
../../../../../node_modules/next/dist/build/adapter/setup-node-env.external.js
… 117 more …
../../../chunks/ssr/node_modules_next_dist_client_components_builtin_global-error_0q-w892nagajq.js
../../../chunks/ssr/node_modules_next_dist_client_components_builtin_unauthorized_0l_sp0xky89qu.js
../../../chunks/ssr/node_modules_next_dist_compiled_@edge-runtime_cookies_index_1kiz_an963mbg.js
../../../chunks/ssr/node_modules_next_dist_esm_build_templates_app-page_1_fz5f9kvpn5j.js
page/react-loadable-manifest.json
page_client-reference-manifest.js

It lists 127 files, each relative to the trace file itself. The first lines are in node_modules, and the packages they name are only @swc/helpers and next: React comes inside next, in the compiled files Next.js ships. The last lines are the build's own files: the route's chunks in server/chunks/ssr/ and the manifests it loads.

With output: "standalone" in next.config.ts, the build uses the traces. writeStandaloneDirectory (build/index.ts, lines 852 to 905) calls copyTracedFiles (build/utils.ts), which copies every file each route's trace lists (lines 1566 to 1578), then every file next-server.js.nft.json lists (line 1585), into .next/standalone, and writes a small server.js there. Then it copies the files required-server-files.json lists, and your .env and .env.production. Here is the tea shop built that way; the Terminal lists the folder:

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  /* config options here */5  cacheComponents: true,6  partialPrefetching: true,7  output: "standalone",8};9 10export 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 (7/7)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ◐ /cart└   /teas/[id]  ├ ◐ /teas/[id]  ├ ○ /teas/green  └ ○ /teas/mint ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content $ cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/ # What .next/standalone holds: 1284 files, 46.2 MB (deeper folders added up).next/standalone/.next/BUILD_ID  21 bytes.next/standalone/.next/app-path-routes-manifest.json  158 bytes.next/standalone/.next/build-manifest.json  2.3 kB.next/standalone/.next/package.json  20 bytes.next/standalone/.next/prerender-manifest.json  9.5 kB.next/standalone/.next/required-server-files.json  10.8 kB.next/standalone/.next/routes-manifest.json  2.3 kB.next/standalone/.next/server/  831.7 kB, 133 files.next/standalone/.next/static/  593.4 kB, 13 files.next/standalone/node_modules/@emnapi/runtime/  66.5 kB, 4 files.next/standalone/node_modules/@img/colour/  46.7 kB, 3 files.next/standalone/node_modules/@img/sharp-darwin-arm64/  281.3 kB, 3 files.next/standalone/node_modules/@img/sharp-libvips-darwin-arm64/  18.2 MB, 6 files.next/standalone/node_modules/@img/sharp-wasm32/  9.3 MB, 5 files.next/standalone/node_modules/@next/env/  11.0 kB, 2 files.next/standalone/node_modules/@swc/helpers/  30.7 kB, 5 files.next/standalone/node_modules/client-only/  467 bytes, 2 files.next/standalone/node_modules/detect-libc/  11.4 kB, 5 files.next/standalone/node_modules/next/  14.6 MB, 993 files.next/standalone/node_modules/react-dom/  1.4 MB, 12 files.next/standalone/node_modules/react/  22.1 kB, 9 files.next/standalone/node_modules/semver/  68.7 kB, 47 files.next/standalone/node_modules/sharp/  631.5 kB, 29 files.next/standalone/node_modules/styled-jsx/  22.3 kB, 4 files.next/standalone/package.json  391 bytes.next/standalone/server.js  8.0 kB

Line 7 of next.config.ts turns it on. The folder's node_modules has next and @swc/helpers, from the page's trace, and also react, react-dom, styled-jsx and sharp (the image library, with its native files for this machine). The page's trace doesn't list those, so they came from the other trace copyTracedFiles reads: next-server.js.nft.json, the server's own, which Turbopack writes too (next_server_nft.rs). The recorder served the page from this folder with node .next/standalone/server.js, after copying in public and .next/static, which the server doesn't trace. The Network tab shows it answered.

The trace is static: it lists what reading the code shows, not what a run loads. A file your code reads with a path made at runtime, like readFile(`./data/${name}.json`), or a native module a package loads in its own way, can be missing from it, and then from .next/standalone. outputFileTracingIncludes is the fix: it adds files to a route's trace. outputFileTracingExcludes removes some, and outputFileTracingRoot says where tracing starts in a monorepo. Self-hosting Next.js runs the standalone folder in Docker.

Answering questions from the .next folder

When a build does something you didn't expect, the files in .next often say why. Some questions the tea shop's team asks, and where each answer is:

• Was this page made during the build? The route table says ○ or ◐, and prerender-manifest.json lists every path that was, with its files in server/app.
• Which file holds this route's server code? server/app-paths-manifest.json.
• Why is this package in my container? Search the .nft.json files for its name: the trace that lists it is the route that needs it, or the server itself.
• Which step was slow? .next/trace has every span's length in microseconds, beside its name.
• Will the next build reuse anything? If .next/cache survives between builds, yes. A CI job that starts from an empty folder each time needs to keep it.

Sort these questions by the manifest that answers them:

Common mix-ups

• "next start builds whatever is missing." No. next start builds nothing. It reads the manifests and serves the files next build wrote; without a build, it stops with an error.
• "Turbopack checks my types." No. Turbopack removes types and compiles. TypeScript checks them in the next step, which is why a type error comes after ✓ Compiled successfully.
• "Generating static pages using 6 workers means six workers rendered pages." No. That's the pool's size. The number of batches is the paths divided by 25, rounded up, and capped at the workers, so a small app's pages make one batch, rendered by one worker, up to 8 at a time.
• "More cores always means more workers." No. The pool never gets more than one worker more than there are routes.
• "The manifests are an API I can build on." No. They're internal files whose names and shapes change between releases. Use the documented APIs.
• "The clean step deletes all of .next." No. It keeps cache, dev, diagnostics, lock and trace.
• "Standalone copies my whole node_modules." No. It copies only the files the .nft.json traces list: the routes' and the server's own.

Practice exercises

Answer each one first, then use the hints.

  Creating an optimized production build ...
✓ Compiled successfully
  Running TypeScript ...
app/teas/[id]/page.tsx(17,18): error TS2322: Type 'number' is not assignable to type 'string'.
Failed to type check.

{
  "/_global-error/page": "app/_global-error/page.js",
  "/_not-found/page": "app/_not-found/page.js",
  "/cart/page": "app/cart/page.js",
  "/page": "app/page.js",
  "/teas/[id]/page": "app/teas/[id]/page.js"
}

function getNumberOfWorkers(config: NextConfigComplete, maxTasks?: number) {
  let workers: number
  …
  } else if (config.experimental.cpus) {
    workers = config.experimental.cpus
  }
  …
  // Cap workers to one more than the number of tasks.
  // Tasks can be passed to avoid over-allocating workers.
  if (maxTasks !== undefined && maxTasks > 0) {
    workers = Math.min(workers, maxTasks + 1)
  }

  return Math.max(workers, 1)
}

const minPageCountPerBatch =
  nextConfig.experimental.staticGenerationMinPagesPerWorker ?? 25

// Calculate the number of workers needed to ensure each batch has at least
// minPageCountPerBatch pages.
const numWorkers = Math.min(
  options.numWorkers,
  Math.ceil(exportPaths.length / minPageCountPerBatch)
)

// Calculate the page count per batch based on the number of workers.
const pageCountPerBatch = Math.ceil(exportPaths.length / numWorkers)

function getNumberOfWorkers(config: NextConfigComplete, maxTasks?: number) {
  let workers: number
  …
  } else if (config.experimental.cpus) {
    workers = config.experimental.cpus
  }
  …
  // Cap workers to one more than the number of tasks.
  // Tasks can be passed to avoid over-allocating workers.
  if (maxTasks !== undefined && maxTasks > 0) {
    workers = Math.min(workers, maxTasks + 1)
  }

  return Math.max(workers, 1)
}

../../../../../node_modules/@swc/helpers/cjs/_interop_require_default.cjs
../../../../../node_modules/@swc/helpers/esm/_interop_require_default.js
../../../../../node_modules/@swc/helpers/package.json
../../../../../node_modules/next/dist/build/adapter/setup-node-env.external.js
… 117 more …
../../../chunks/ssr/node_modules_next_dist_client_components_builtin_global-error_0q-w892nagajq.js
../../../chunks/ssr/node_modules_next_dist_client_components_builtin_unauthorized_0l_sp0xky89qu.js
../../../chunks/ssr/node_modules_next_dist_compiled_@edge-runtime_cookies_index_1kiz_an963mbg.js
../../../chunks/ssr/node_modules_next_dist_esm_build_templates_app-page_1_fz5f9kvpn5j.js
page/react-loadable-manifest.json
page_client-reference-manifest.js

Check your understanding

For each question, think about which step runs where, and which file it writes.

Key takeaways

• build in build/index.ts runs the steps in order: settings, routes, the Turbopack compile, the type check, page data, prerendering, the manifests, and the route table. .next/trace lists them by name.
• A failed build stops at the first step that can see the problem: a missing file in the compile, a type error after it, a throwing page while prerendering.
• Prerendering runs in a pool of worker processes: the cores minus one, at most one more than the routes. The number of batches is the paths divided by 25, rounded up and capped at the workers; the paths are cut into equal slices, one per batch, and each worker renders up to 8 at a time.
• The manifests describe the build for the server. The router server reads the route lists when it starts; each route's code reads the rest when its first request comes.
• Each route's .nft.json lists the files its code loads. output: "standalone" copies those, and the server's own, into .next/standalone.
• Everything in .next is readable, and all of it is this version's internals: read it, don't build on it.

Coming next: SWC and Turbopack. It opens step 3: the Rust compiler that transforms each file, and the bundler that builds one module graph for the server and the browser.