---
title: "Getting Started"
description: "Install next-bun-compile and ship your first Next.js binary in minutes."
---

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

# Getting Started

## Requirements

- [Bun](https://bun.sh) >= 1.3
- [Next.js](https://nextjs.org) >= 16.2.0

## Setup

1. ### Install

### bun

```bash
   bun add -D next-bun-compile
```
### npm

```bash
   npm install -D next-bun-compile
```
### pnpm

```bash
   pnpm add -D next-bun-compile
```
### yarn

```bash
   yarn add -D next-bun-compile
```

2. ### Point Next.js at the build adapter

   next-bun-compile is a [Next.js Build Adapter](https://nextjs.org/docs/app/api-reference/config/next-config-js/adapterPath).
   Add `adapterPath` to your `next.config.ts`:

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

```bash
   NEXT_ADAPTER_PATH=next-bun-compile next build
```

3. ### Build the binary

```bash
   next build
```

   One command. Produces a single `./dist/app` executable next to your
   `package.json`.

4. ### Run it

```bash
   ./dist/app
```

   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

```bash
PORT=3000 ./dist/app &
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](/next-bun-compile/next-bun-compile/recipes/distroless-sharp/)
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](/next-bun-compile/next-bun-compile/recipes/distroless-sharp/).
- **Monorepos** are supported out of the box. See the
  [Monorepo guide](/next-bun-compile/next-bun-compile/guides/monorepo/).
- **Something went wrong?** Check [Troubleshooting](/next-bun-compile/next-bun-compile/troubleshooting/).
- **Curious how the binary actually works?** See
  [How it works](/next-bun-compile/next-bun-compile/how-it-works/).

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