bun-bundle

4.0.3 verified Sat Apr 25 auth: no javascript

bun-bundle is a lightweight module bundler that wraps Bun.build, providing a simplified API for bundling JavaScript and TypeScript projects. As of version 4.0.3 (released in late 2024), it supports ESM output, HTML entrypoints, and conditional entry naming. Compared to Bun's native build API, bun-bundle offers a less opinionated configuration and automatic handling of common patterns. It is actively maintained with frequent releases, focusing on simplicity and ease of use for projects targeting Bun runtime.

Common errors

error Error: Cannot find module 'bun-bundle' ↓

cause Project not installed or using CommonJS require in an ESM-only package (v3+).

fix

Run 'bun install bun-bundle' (or 'npm install') and use ESM imports (import ... from 'bun-bundle').

error TypeError: bundle is not a function ↓

cause Default import used instead of named import.

fix

Change 'import bundle from' to 'import { bundle } from'.

error Error: BundleBuildConfig is not a type ↓

cause Using old type name BunBundleBuildConfig from v2.x.

fix

Use 'BunBundleConfig' instead.

Warnings

breaking The API was simplified in v3.0.0, removing many previously required options and changing the function signature. ↓

fix Update your code to use the new flat configuration object. Refer to the v3 migration guide.

breaking v4.0.0 introduced support for HTML entrypoints. Existing code that relied on default JS-only entrypoints may need to specify entrypoints explicitly. ↓

fix If you were using implicit JS entrypoints, migrate to explicit entrypoints in your configuration.

gotcha bun-bundle requires Bun runtime to be installed globally or in the project. Running the bundler in Node.js will fail with a runtime error. ↓

fix Ensure you run your script with Bun (e.g., bun run build.js). Do not use node.

gotcha The 'target' option must be set to 'bun' for optimal compatibility. Using 'node' or 'browser' may cause issues with Bun-specific features like node:buffer. ↓

fix Set target: 'bun' in your configuration.

Install

npm install bun-bundle

yarn add bun-bundle

pnpm add bun-bundle

Imports

bundle
wrong
```
import bundle from 'bun-bundle'
```
correct
```
import { bundle } from 'bun-bundle'
```
bundle is a named export, not default. Incorrect default imports will result in undefined.
BunBundleConfig
wrong
```
import { BunBundleBuildConfig } from 'bun-bundle'
```
correct
```
import { BunBundleConfig } from 'bun-bundle'
```
In v2.1.1, the type was named BunBundleBuildConfig, but it was renamed to BunBundleConfig in v3+.
bundleSync
wrong
```
const { bundleSync } = require('bun-bundle')
```
correct
```
import { bundleSync } from 'bun-bundle'
```
The package is ESM-only since v3. CommonJS require will cause a Module not found error.

Quickstart

Demonstrates basic usage of the bundle function with common options: entrypoints, output directory, target, format, and minification.

import { bundle } from 'bun-bundle';

const result = await bundle({
  entrypoints: ['./src/index.ts'],
  outdir: './dist',
  target: 'bun',
  format: 'esm',
  splitting: true,
  sourcemap: 'external',
  minify: true,
});

console.log(`Bundled ${result.outputs.length} files successfully`);