Skip to content

Commit 593e108

Browse files
committed
docs: correct the claim that Turbopack ignores outputFileTracingIncludes
Two documents said Next skips trace collection under Turbopack and concluded the option therefore never runs. The first half is true and the conclusion does not follow: `collectBuildTraces` is skipped, but Turbopack emits the `.nft.json` files and applies the include globs itself. Measured against a Turbopack build of this app rather than argued from `next/dist`: `next-server.js.nft.json`, which the `'/**'` key does not cover, lists three `@swc/helpers` entries and none under `esm/`; a route's `.nft.json`, which it does cover, lists over a thousand including 324 under `esm/` and the package's `LICENSE`, a file no tracer would follow. The glob is load-bearing, not dead code, and the gate guarding its pinned version guards something real. That reading also produced a false explanation for the missing migration `.sql` files on Vercel. They are absent because nothing imports them and nothing lists them, not because the mechanism is unavailable — the schema-check the installer now does stands on its own arguments, which were always the better ones. And the reason `output: 'standalone'` broke the Vercel build is recorded as unestablished rather than explained by a mechanism that does not hold. The positive fact is written down beside the glob it explains, because reading `next/dist` alone leads to the wrong conclusion twice.
1 parent 846474b commit 593e108

2 files changed

Lines changed: 22 additions & 10 deletions

File tree

docs/development.md

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -155,10 +155,11 @@ tree**, right after `next build` finishes. `next.config.mjs` sets
155155
`output: 'standalone'` everywhere the board has to serve itself — which is
156156
everywhere except Vercel, where Vercel packages the build into its own
157157
functions and never runs `forum-web start`. Asking for standalone there
158-
breaks the build outright: standalone makes Vercel's builder read
159-
`.next/next-server.js.nft.json`, and Next skips the tracing that writes it
160-
whenever the bundler is Turbopack, which is the default for `next build` in
161-
Next 16. Next's own standalone output deliberately
158+
breaks the build outright: standalone makes Vercel's builder look for
159+
`.next/next-server.js.nft.json`, and on that deployment it was not there.
160+
Why it was missing was never established — a Turbopack build does write
161+
that file, as the tracing note below records — so treat the mechanism as
162+
open and the failure as observed. Next's own standalone output deliberately
162163
excludes both directories — they have to be copied in alongside the traced
163164
`server.js` for it to serve `/_next/static/*` and anything under `public/`
164165
(Next's bundled docs, under `node_modules/next/dist/docs`, say so under
@@ -214,6 +215,18 @@ worst place to learn it. The check reads both configs that carry the literal
214215
carrying one at all. The second, unversioned glob beside it covers the hoisted
215216
layout npm installs, where no `.pnpm` directory exists for the first to match.
216217

218+
**`outputFileTracingIncludes` is applied by Turbopack itself**, which is worth
219+
stating because the option is handled in `next/dist` only by
220+
`collectBuildTraces`, and `next build` skips that function entirely when the
221+
bundler is Turbopack — reading only that far suggests the glob above is dead
222+
code, and it is not. Turbopack emits the `.nft.json` files and applies the
223+
include globs on its own side. Measured on a Turbopack build of this app:
224+
`next-server.js.nft.json`, which the `'/**'` key does not cover, lists three
225+
`@swc/helpers` entries and none under `esm/`; a route's `.nft.json`, which it
226+
does cover, lists over a thousand including 324 under `esm/` and the package's
227+
`LICENSE` — a file no tracer would follow. Delete the glob on the theory that
228+
nothing reads it and self-hosted boards go back to failing at request time.
229+
217230
**This assumes a hoisted `node_modules`** — npm, yarn classic, or pnpm with
218231
`node-linker=hoisted` (`create-meith`'s own scaffold uses npm). The
219232
materialized app's source imports every `@meith/*` package it needs by bare

docs/vercel.md

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -361,12 +361,11 @@ then come back for the four things specific to this route:
361361
contend for the same migration lock, and the function timeout bounds how
362362
long a migration is allowed to take. The step reads the table names out
363363
of the schema definitions, which are ordinary imported code, because the
364-
migration `.sql` files are not in the function at all: nothing imports
365-
them, so nothing traces them in, and `outputFileTracingIncludes` cannot
366-
put them back while `next build` defaults to Turbopack, for which Next
367-
skips trace collection entirely. If that step does report missing tables,
368-
run `community migrate` against the same database and reload — do not
369-
reach for `MIGRATIONS_DIR`, which cannot help when the files are absent.
364+
migration `.sql` files are not in the function: nothing imports them, so
365+
nothing traces them in, and nothing lists them in
366+
`outputFileTracingIncludes` either. If that step does report missing
367+
tables, run `community migrate` against the same database and reload —
368+
`MIGRATIONS_DIR` cannot help when the files are absent.
370369
- **The installer takes the same session-level advisory lock migrations
371370
do**, so it needs `DIRECT_DATABASE_URL` for the same reason. Run against
372371
a pooler, it can report itself permanently in flight.

0 commit comments

Comments
 (0)