libuild

Zero-config library builds with ESBuild.

Libuild is a build tool for JavaScript/TypeScript libraries which publish to NPM. It solves ESM/CJS support, type generation, and produces clean packages with just the files and configuration needed by consumers.

Installation

npm install -D @b9g/libuild
bun add -d @b9g/libuild

Usage

# Build your library (development mode - no package.json changes)
libuild build

# Build and update package.json for npm link
libuild build --save

# Build and publish to npm
libuild publish

Features

• No configuration - Source files and standard package.json are all you need
• Multiple formats - Supports ESM, CJS, UMD, and generates d.ts files
• Clean output - Only necessary files and fields go into the package
• Development-friendly - NPM link just works and changes can be saved to package.json

Convention = Configuration

Entry Points

• Library modules: All top-level .js/.ts files in src/ (excluding _ prefixed files)
• Workers: A src/<name>.worker.ts is built to dist/<name>.worker.js but left out of exports. It is for code that is loaded by file path - new Worker(new URL("./decode.worker.js", import.meta.url), {type: "module"}) - which never goes through the exports map, so there is nothing to make public. ESM only.
• CLI binaries: Any file referenced in package.json bin field gets compiled to standalone executable
• UMD builds: If src/umd.ts exists, creates browser-compatible UMD build

Output Structure

• Flat output: src/index.ts → dist/index.js - modules publish at the package root, so direct CDN URLs like cdn.jsdelivr.net/npm/<pkg>/index.js just work
• Executables: bin/cli.ts → dist/bin/cli.js (bin/ stays a subdirectory)
• ESM: .js files with ES module syntax
• CommonJS: .cjs files for Node.js compatibility
• TypeScript: .d.ts declaration files for all modules (when TypeScript is available); internal modules relocate together with their imports intact
• Module augmentation: declare module blocks are preserved in .d.ts output
• Code splitting: Dynamic imports create chunks in dist/_chunks/
• Clean package.json: Optimized for consumers (no dev scripts)

Format Control

• ESM-only: Remove the main field from package.json to skip CommonJS builds
• CommonJS detection: Presence of main field enables .cjs builds
• UMD builds: Add src/umd.ts for browser-compatible builds

Export Aliases

• Legacy support: ./entry.js automatically aliases to ./entry
• Package.json: Always exported as ./package.json
• Custom exports: Existing exports in package.json are preserved and enhanced

Package.json Transformations

• Development mode (default): Root package.json unchanged, no git noise
• --save mode: Root package.json updated to point to ./dist/* artifacts for npm link
• Dist package.json: Clean consumer-ready version with root-relative paths
• Bin paths: Automatically transformed from src/ references to built artifacts
• Exports field: Generated for all entry points with proper types-first ordering

Examples

Simple Library

Given this structure:

src/
  index.ts
  utils.ts
  _internal.ts  # ignored (underscore prefix)

Produces:

dist/
  index.js         # ESM
  index.cjs        # CommonJS
  index.d.ts       # TypeScript declarations
  utils.js
  utils.cjs
  utils.d.ts
  package.json     # Clean consumer version

Library with CLI

package.json:
{
  "bin": { "mytool": "src/cli.js" }
}

src/
  index.ts
  cli.ts

Produces:

dist/
  index.js
  index.cjs
  index.d.ts
  cli.js           # Compiled CLI (dual-runtime shebang, executable)
  cli.cjs
  cli.d.ts
  package.json     # bin: { "mytool": "cli.js" }

ESM-Only Library

To build only ESM (no CommonJS), remove the main field:

// package.json
{
  "name": "my-lib",
  "module": "dist/index.js",  // ESM entry
  "types": "dist/index.d.ts"
  // no "main" field = no CJS
}

Produces:

dist/
  index.js         # ESM only
  index.d.ts
  utils.js         # ESM only
  utils.d.ts
  package.json     # ESM-only exports

Multi-Format with UMD

src/
  index.ts
  utils.ts
  umd.ts         # Browser build entry

Produces:

dist/
  index.js
  index.cjs
  index.d.ts
  utils.js
  utils.cjs
  utils.d.ts
  umd.js           # UMD browser build
  package.json

Generated Package.json Exports

Dual format (ESM + CommonJS):

{
  "main": "index.cjs",
  "module": "index.js",
  "types": "index.d.ts",
  "exports": {
    ".": {
      "types": "./index.d.ts",
      "import": "./index.js",
      "require": "./index.cjs"
    },
    "./utils": {
      "types": "./utils.d.ts",
      "import": "./utils.js",
      "require": "./utils.cjs"
    },
    "./utils.js": {
      "types": "./utils.d.ts",
      "import": "./utils.js",
      "require": "./utils.cjs"
    },
    "./package.json": "./package.json"
  }
}

ESM-only (no main field in source):

{
  "module": "index.js",
  "types": "index.d.ts",
  "type": "module",
  "exports": {
    ".": {
      "types": "./index.d.ts",
      "import": "./index.js"
    },
    "./utils": {
      "types": "./utils.d.ts",
      "import": "./utils.js"
    },
    "./utils.js": {
      "types": "./utils.d.ts",
      "import": "./utils.js"
    },
    "./package.json": "./package.json"
  }
}

Root package.json (with --save):

{
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

Commands

libuild build (default)

Builds your library in development mode:

• Compiles all entry points to multiple formats
• Generates TypeScript declarations
• Creates optimized package.json files
• Preserves root package.json (no git noise)

libuild build --save

Builds and updates root package.json for npm link:

• Everything from libuild build
• Updates root package.json to point to dist artifacts
• Perfect for testing with npm link

libuild publish

Builds and publishes to npm:

• Runs full build with --save
• Warns if root package.json is not private
• Publishes from dist directory with clean package.json

Requirements

• Node.js 20.10+ or Bun 1.0+ (for running libuild)
• TypeScript (optional, for .d.ts generation)
• No runtime requirements for library consumers

Testing: libuild test

Runs your suite across runtimes with one command and one set of test files:

libuild test                        # bun, current directory
libuild test tests -p bun -p node   # both runtimes
libuild test -p deno                # deno, via `deno test`
libuild test -p chromium            # real browser via Playwright
libuild test path/to/one.test.ts    # single-file loop

Deno runs the same files through its own deno test, which bridges node:test into it, so no Deno-specific test API is needed, and the summary reads the same on all three runtimes.

Import the portable API from @b9g/libuild/test (describe/test/it/expect, hooks, test.concurrent, .each, and a cross-runtime toMatchSnapshot). Files run in per-file isolated processes with dependencies resolved from your node_modules; import.meta.url/.dirname/.filename and __dirname/__filename point at your source files, not the bundles.

Flags: --timeout <ms> is the per-file budget, and on bun it is also applied as the per-test timeout (bun defaults to 5s per test; without this, slow tests die before the file budget matters). --concurrency <n> caps how many files run at once — lower it for suites whose tests spawn their own processes. --filter <glob> selects files; -u updates snapshots; --debug keeps the browser open and preserves the bundle directory.

Coverage

libuild test --coverage -p node collects coverage on the node shards and prints a table after the run, with lines mapped back to your source files through the bundles' source maps. --coverage-reporter lcov html picks c8's reporters (default text); file reports go to coverage/, or --coverage-dir <dir>. Test files and declaration files are left out. Coverage is node-only: bun does not write V8 coverage for a bundle and deno writes its own format, so shards on those runtimes run as usual and collect nothing.

In-source tests

Tests can live in the module they cover, the way Rust's mod tests does. They share the module's closure, so they can reach helpers and state that is never exported:

const SEEN = new Map<string, number>();

function memoKey(a: number, b: number) { return `${a}:${b}`; }

export function addMemo(a: number, b: number) {
  const key = memoKey(a, b);
  if (SEEN.has(key)) { return SEEN.get(key)!; }
  const out = a + b;
  SEEN.set(key, out);
  return out;
}

if (import.meta.litest) {
  const {test, expect} = import.meta.litest;

  test("memoizes", () => {
    expect(addMemo(1, 2)).toBe(3);
    expect(SEEN.get(memoKey(1, 2))).toBe(3);   // never exported
  });
}

There is nothing to import: import.meta.litest is the test API, the same surface @b9g/libuild/test exports. libuild test injects it and runs these files alongside your *.test.* suite; any file under src/ containing the guard is discovered.

libuild build removes the block completely — the assertions, and any import only the test needed. Nothing about the published package reveals the tests were there, and consumers never need libuild installed to load your library.

Two things worth knowing:

• Write the guard as if (import.meta.litest). Discovery looks for exactly that, so a test block behind a different expression is stripped from the build but never run.
• Files containing in-source tests are syntax-minified in dist (if/continue collapsed to ||, and so on). Removing the block requires constant folding, which libuild applies per file rather than turning it on for the whole build — so modules without in-source tests keep byte-identical output.

The same guard gates test-only code that is not a test. A check that runs in a frame loop under test, and must not ship, sits behind if (import.meta.litest): in every test bundle the expression is the test API, so the check runs; in the build it is undefined and the guarded code is stripped, and a function only it called goes with it.

For TypeScript, add libuild's ambient declaration to your tsconfig.json:

{"compilerOptions": {"types": ["@b9g/libuild/litest.d.ts"]}}

Runtime notes:

• bun cannot nest test() inside test() (oven-sh/bun#5090). Notably, ESLint's RuleTester registers nested subtests, so rule suites hit NotImplementedError on bun — either run those with -p node, or flatten RuleTester's hooks (RuleTester.describe = (_n, fn) => fn() inside one enclosing test) to stay portable.
• libuild is ESM-only: packages declaring "type": "commonjs" are refused (packages with no type field are fine). CJS is produced only as the build's main-field fallback.

License

MIT