Bundling and file tracing

Next.js uses @vercel/nft during production builds to emit an .nft.json file for every server route. Each trace lists the files that must be available when that route runs in a Vercel function or another minimal deployment.

Monorepo tracing root

Every CentraKit app passes the repository root to the shared config factory as outputFileTracingRoot. This is explicit even though Next.js can infer the same root from the workspace lockfile.

The explicit root is required for two repository conventions:

• pnpm stores real package files under the repository-level node_modules/.pnpm/ directory.
• Some apps read generated or authored files from sibling apps at runtime.

Do not move the root back to an inferred default. A lockfile or build invocation change could otherwise make valid workspace dependencies fall outside the trace.

When to add an include

Normal static import, require, and recognizable fs calls should be left to nft. Add outputFileTracingIncludes only when runtime code deliberately prevents static discovery, or when a deployment treats the file separately from the server function.

Current examples:

• Generated OpenAPI spec: the API MCP route reads apps/api/public/openapi.json at request time. Vercel serves public/ separately, so /api/mcp explicitly includes the file in its function trace.
• Cross-app docs sources: the docs app reads the API spec and app CHANGELOG.md files outside apps/docs. Its server traces include those sibling files.
• Barcode WASM: the zxing route assembles the module specifier from string parts so Turbopack serves the Emscripten binary as bytes instead of compiling it. That also hides the file from nft, so the route explicitly includes zxing_reader.wasm.

Include keys are route globs and include values are resolved from the app directory, not the monorepo root. Keep both as narrow as possible. Fully static routes do not produce server trace files, so includes do not apply to them.

PDF and Workflow bundles

@react-pdf/renderer and qrcode stay in serverExternalPackages. Their runtime require graphs are visible to nft, and the monorepo tracing root lets nft follow those graphs into pnpm's store. Do not add a broad PDF package include unless a build trace proves a required asset is missing.

Workflow v5 owns transpilation for workflow and @workflow/*; do not add those packages to serverExternalPackages. withWorkflow generates app/.well-known/workflow/v1/flow/route.js, which Next.js traces like any other server route. Step-only imports therefore belong in the flow trace, including React PDF when an invoice or quote step renders a document.

Keep app/.well-known/workflow/** in apps/saas/turbo.json and apps/api/turbo.json build outputs (Workflow SDK Turborepo caching). Local builds resolve @workflow/world-local; Vercel builds resolve @workflow/world-vercel.

Because both services ship Workflow consumers in one Vercel project, pin distinct WORKFLOW_QUEUE_NAMESPACE values (saas / api) so queue topics become __saas_wkf_workflow_* and __api_wkf_workflow_* instead of colliding on __wkf_workflow_* / consumer default.

Trace size hygiene

Only exclude a package when the server can never execute it. Streamdown performs syntax highlighting during SSR, so Shiki language and theme assets are real server dependencies and must not be excluded.

CentraKit instead overrides @streamdown/code to the catalog Shiki version. This prevents pnpm and nft from carrying two complete grammar bundles while preserving server-side highlighting.

Verification

Build the traced apps and run the regression guard:

pnpm test:tracing

The task builds all five Next.js apps, then checks:

• every app reports the repository as outputFileTracingRoot;
• the API and docs runtime data files are present;
• the zxing WASM binary is present;
• both a PDF route and the Workflow flow route contain React PDF dependencies;
• the SaaS trace contains one Shiki language-bundle version.

The guard lives in tests/build/output-file-tracing.test.ts. It resolves every path relative to its .nft.json file, matching Next.js trace semantics. For manual investigation, inspect:

• apps/<app>/.next/required-server-files.json for the serialized tracing configuration;
• apps/<app>/.next/server/app/**/route.js.nft.json for route dependencies;
• apps/saas/.next/server/app/.well-known/workflow/v1/flow/route.js.nft.json for the combined Workflow step bundle.