@savvy-web/bun-builder

A high-performance build system for modern ESM Node.js libraries using Bun's native bundler. Build TypeScript packages with automatic entry detection, declaration bundling, and package.json transformation in milliseconds.

Features

• Sub-Second Builds - Leverages Bun's native bundler for fast iteration
• Zero Configuration - Auto-detects entry points from package.json exports
• Declaration Bundling - Generates rolled-up .d.ts files via tsgo + API Extractor
• Catalog Resolution - Resolves Bun's catalog: and workspace: protocols for npm publishing
• Multi-Target Output - Single configuration produces both dev and npm builds
• API Documentation - Generates .api.json files for documentation tools
• Self-Building - This package builds itself using BunLibraryBuilder

Installation

bun add -D @savvy-web/bun-builder

Peer Dependencies

bun add -D @microsoft/api-extractor @typescript/native-preview typescript @types/bun

Quick Start

Create a bun.config.ts file in your project root:

import { BunLibraryBuilder } from '@savvy-web/bun-builder';

export default BunLibraryBuilder.create({});

Add build scripts to your package.json:

{
  "scripts": {
    "build": "bun run bun.config.ts",
    "build:dev": "bun run bun.config.ts --env-mode dev",
    "build:npm": "bun run bun.config.ts --env-mode npm"
  }
}

Run the build:

bun run build

TypeScript Configuration

The package includes a pre-configured tsconfig.json optimized for library builds:

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "extends": "@savvy-web/bun-builder/tsconfig/ecma/lib.json"
}

This configuration includes:

• ESNext target with bundler module resolution
• Strict type checking enabled
• Declaration generation for library distribution
• Support for .ts, .tsx, .mts, .cts, and .json files

Usage

The builder automatically extracts entry points from your package.json exports:

{
  "name": "my-library",
  "exports": {
    ".": "./src/index.ts",
    "./utils": "./src/utils.ts"
  }
}

// bun.config.ts
import { BunLibraryBuilder } from '@savvy-web/bun-builder';

export default BunLibraryBuilder.create({
  // Keep certain packages as external dependencies
  externals: ['lodash', /^@aws-sdk\//],

  // Bundle type definitions from these packages into your .d.ts
  dtsBundledPackages: ['type-fest'],

  // Enable TSDoc validation before build
  tsdocLint: true,

  // Generate API model for documentation tools
  apiModel: true,
});

Build Targets

Two output targets with different optimizations:

| Target | Source Maps | Output Directory | Description | |--------|-------------|------------------|------------------------------------------| | dev | linked | dist/dev/ | Development build with debugging support | | npm | none | dist/npm/ | Optimized for npm publishing |

Select a specific target via CLI:

bun run bun.config.ts --env-mode dev   # Dev build only
bun run bun.config.ts --env-mode npm   # npm build only
bun run bun.config.ts                  # Both targets

Build Output

The build produces bundled ESM output with rolled-up types:

  bun-builder v0.2.0

info    Building targets: dev, npm
info    auto-detected entries { index: "./src/index.ts" }
info    Using tsconfig: tsconfig.json
info    [dev] build started...
info    [dev] Bundled 1 file(s) in 42ms
info    [dev] Generating declaration files...
info    [dev] Generated declarations in 156ms
info    [dev] Emitted 1 bundled declaration file in 89ms
ready   [dev] built in 287ms

  dist/dev (dev)
  File            Size
  index.js        12.4 KB
  index.d.ts       2.1 KB
  package.json     0.5 KB

Requirements

• Bun >= 1.3.0
• Node.js >= 20.0.0 (for peer dependencies)
• TypeScript >= 5.5.0

Documentation

• Configuration Reference - Complete options documentation
• Package.json Transformation - How exports and dependencies are transformed
• Declaration Bundling - TypeScript declaration generation
• Advanced Usage - Programmatic API and custom pipelines

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT