Getting Started

Requirements

• Bun >= 1.3
• Next.js >= 16.2.0

Setup

1. Install

   bun

   bun add -D next-bun-compile

   npm

   npm install -D next-bun-compile

   pnpm

   pnpm add -D next-bun-compile

   yarn

   yarn add -D next-bun-compile

2. Point Next.js at the build adapter

   next-bun-compile is a Next.js Build Adapter. Add adapterPath to your next.config.ts:

   import type { NextConfig } from "next";
   
   const nextConfig: NextConfig = {
     adapterPath: "next-bun-compile",
   };
   
   export default nextConfig;

   No output: "standalone" needed — the adapter assembles its own traced output tree. You can also enable it without touching the config at all:

   NEXT_ADAPTER_PATH=next-bun-compile next build

3. Build the binary

   next build

   One command. Produces a single ./server executable next to your package.json.

4. Run it

   ./server

   Listens on port 3000 by default. Configurable via the PORT env var.

Migrating from the CLI (v0.x)

Three changes:

1. Remove output: "standalone" from next.config.ts and add adapterPath: "next-bun-compile".
2. Change your build script from next build && next-bun-compile to just next build.
3. Cross-compiling? --target=bun-linux-x64 becomes NBC_TARGET=bun-linux-x64 next build.

What’s in the binary?

• Your Next.js server runtime (chunks, manifests, build ID)
• Static assets (.next/static/*) and public files (public/*)
• Prerendered pages and their RSC payloads
• All externalized server packages (sharp, prisma, anything in serverExternalPackages, etc.)
• The bun runtime itself (you don’t need bun on the deploy target)

At runtime, static assets and fully-static prerendered pages are served directly from memory; ISR and cache-component responses get an in-memory cache that Next’s own revalidation invalidates. The binary extracts its server runtime files to disk on first run (or to NBC_RUNTIME_DIR — point it at tmpfs for read-only filesystems), and skips extraction on subsequent runs of the same build.

Verify it works

PORT=3000 ./server &
curl http://localhost:3000/

You should see your homepage HTML. From here, the typical next step is putting it in a Docker image — see the Distroless + sharp recipe for a complete working Dockerfile.

Next steps

• Native deps like sharp need a runner image with the right C libraries. See Native dependencies in Docker.
• Monorepos are supported out of the box. See the Monorepo guide.
• Something went wrong? Check Troubleshooting.
• Curious how the binary actually works? See How it works.