---
title: "Configuration"
description: "Environment variables and Next.js config options that affect next-bun-compile."
---

> Documentation Index
> Fetch the complete documentation index at: https://ramonmalcolm10.github.io/next-bun-compile/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

## Environment variables (runtime)

| Variable                   | Default              | Description                                                       |
| -------------------------- | -------------------- | ----------------------------------------------------------------- |
| `PORT`                     | `3000`               | Server port                                                       |
| `HOSTNAME`                 | `0.0.0.0`            | Server hostname                                                   |
| `KEEP_ALIVE_TIMEOUT`       | —                    | HTTP keep-alive timeout (ms)                                      |
| `NBC_RUNTIME_DIR`          | binary's directory   | Where runtime files extract and `.next/cache` lives. Point at tmpfs (e.g. `/tmp/app`) for RAM-backed runtime files and read-only root filesystems. |
| `NBC_PPR_SHELL`            | off                  | Enables the edge-shell endpoint for PPR routes. `1`/`true` serves openly; any other value is a shared token required in `x-nbc-shell-token`. See [Edge PPR](/next-bun-compile/next-bun-compile/guides/edge-ppr/). |
| `NEXT_BUN_COMPILE_DEBUG`   | `0`                  | Set to `1` to log every resolver-hook decision. See [Debug mode](/next-bun-compile/next-bun-compile/guides/debug-mode/). |

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](/next-bun-compile/next-bun-compile/guides/docker/#pre-extract-at-image-build---extract).

## Environment variables (build time)

| Variable                   | Default        | Description                                                       |
| -------------------------- | -------------- | ----------------------------------------------------------------- |
| `NEXT_ADAPTER_PATH`        | —              | Enable the adapter without touching `next.config`: `NEXT_ADAPTER_PATH=next-bun-compile next build` |
| `NBC_TARGET`               | host platform  | Cross-compile target, e.g. `bun-linux-x64`. See [Cross-compilation](/next-bun-compile/next-bun-compile/guides/cross-compilation/). |
| `NBC_OUT`                  | `dist`         | Directory for the compiled binary (created if missing), relative to the project or absolute. See [Where the binary appears](#where-the-binary-appears). |
| `NBC_BINARY`               | `app`          | Filename of the compiled binary.                                  |
| `NBC_BUILD_ARGS`           | —              | Extra flags appended to the `bun build` invocation, whitespace-separated. See [Extra build flags](#extra-build-flags). |
| `NEXT_BUN_COMPILE_VERBOSE` | `0`            | Set to `1` to print the alias-resolution table at 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.

```bash
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):

|                                | default   | `--bytecode` | change |
| ------------------------------ | --------- | ------------ | ------ |
| Time to listening              | 34.8 ms   | 28.9 ms      | −17%   |
| Time to first dynamic response | 177.3 ms  | 175.7 ms     | −0.9%  |
| Binary size                    | 76.7 MB   | 78.2 MB      | +2.0%  |

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)

```ts
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:

```ts
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.

```ts
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:

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

See the [transpilePackages guide](/next-bun-compile/next-bun-compile/guides/transpile-packages/)
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):

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

The directory is created if it doesn't exist.

:::caution[Changed in v2]
The binary is written to **`dist/app`**. Before v2 it was `./server` in the
project root.

A 78MB executable named `server` lands where source lives, is easy to commit
by accident, and collides with framework conventions (Nitro treats `server/`
as a convention dir). `dist/` is the conventional place for build output.

Deploy scripts, Dockerfiles and `.gitignore` entries that name `./server`
need updating. To keep the old location instead:

```bash
NBC_OUT=. NBC_BINARY=server next build   # → ./server, as in v1
```
:::

Source: https://ramonmalcolm10.github.io/next-bun-compile/configuration/index.mdx