Configuration

Environment variables (runtime)

The binary also accepts one flag: server --extract extracts the runtime tree to NBC_RUNTIME_DIR and exits — run it at image build time so container boots skip extraction. See Pre-extract at image build.

Environment variables (build time)

Extra build flags

NBC_BUILD_ARGS appends flags to the bun build call that produces the binary, after the adapter’s own defaults. The adapter runs inside next build and has no argv of its own, so this is the only way in.

NBC_BUILD_ARGS="--bytecode" next build

Flags only — the value is split on whitespace, with no quoting.

Should you enable --bytecode?

Usually not. Bun’s bytecode cache covers the statically bundled entry graph, but almost all request-path code — Next itself, SSR chunks, your pages, externalised packages — is extracted to disk and loaded through computed requires the bundler never sees. Measured on examples/vps-deploy (bun 1.4.0, macOS arm64, 25 interleaved warm boots, median):

The ~6 ms saved on the entry graph disappears behind the ~145 ms spent requiring Next off the extracted tree. It is worth enabling only if your app is served entirely from Tier 1 / Tier 2 routes and never initialises Next, in which case you only ever pay the first row.

next.config.ts options

adapterPath (required)

const nextConfig: NextConfig = {
  adapterPath: "next-bun-compile",
};

This makes next build produce the binary directly. output: "standalone" is not required (and not used) — the adapter assembles its own traced output tree from the build.

In monorepos or linked workspaces, Next resolves adapterPath from its own package location — resolve from the app dir instead:

import { createRequire } from "node:module";
const req = createRequire(process.cwd() + "/");

const nextConfig: NextConfig = {
  adapterPath: req.resolve("next-bun-compile"),
};

assetPrefix (optional, optimizes binary size)

If you set assetPrefix for a CDN, next-bun-compile detects it and skips embedding static assets in the binary — your CDN serves them instead. Only public/ files and runtime chunks get embedded.

const nextConfig: NextConfig = {
  adapterPath: "next-bun-compile",
  assetPrefix: "https://cdn.example.com",
};

You’ll need to upload .next/static/ to your CDN separately.

transpilePackages (optional, for packages with dynamic requires)

Some packages use dynamic require() calls internally that Turbopack can’t resolve at build time. Force them through the bundler instead:

const nextConfig: NextConfig = {
  adapterPath: "next-bun-compile",
  transpilePackages: ["pino", "pino-pretty"],
};

See the transpilePackages guide for when you need this.

Custom cache handlers

If you configure a custom cacheHandler, the in-memory page tiers turn themselves off automatically — every page request goes through Next exactly as it would under next start. Static assets are still served from memory.

The reason is multi-instance semantics, not observability: a custom handler is typically a shared store (Redis), where an invalidation issued on one instance is expected to take effect on all of them. Next honors that by reading through your handler on every request; a frozen in-memory copy on another instance would never hear about the invalidation.

Where the binary appears

By default, ./dist/app next to the package.json of the project being built. In a monorepo, this is apps/<your-app>/dist/app. Monorepo layouts are detected automatically.

Override the location with NBC_OUT (directory) and NBC_BINARY (filename):

NBC_OUT=build NBC_BINARY=server next build   # → ./build/server

The directory is created if it doesn’t exist.