bao-bundler

library0.2.4jsnpmunverified

Bao Bundler is a simple, code-driven asset bundler for web projects, engineered specifically for the Bun runtime. As of version 0.2.4, it offers an imperative build process through its core concepts of `Project`, `Flows` (defining what to bundle from sources like folders or files), and `Runners` (defining how to process assets, such as copying them). This approach grants maximum flexibility by allowing developers to define build steps directly in TypeScript code, diverging from configuration-file-driven bundlers. The package is in an early development phase, suggesting an active but potentially irregular release cadence as new features and refinements are introduced. Its key differentiator is the tight integration with Bun, leveraging Bun's performance for asset processing, and its highly customizable pipeline through custom `Flow` and `Runner` implementations.

devops web-framework

npm install bao-bundler

package ↗

INSTALL

IMPORT

SIG · BAO-BUNDLER

bao-bundler

devopsjavascriptv0.2.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Project

✓ import { Project } from 'bao-bundler';

✗ const Project = require('bao-bundler').Project;

Bao Bundler is an ESM-only package, designed for Bun. CommonJS 'require' is not supported.

FolderFlow, FileFlow

✓ import { FolderFlow, FileFlow } from 'bao-bundler/flows';

✗ import { FolderFlow } from 'bao-bundler';

Flow implementations like FolderFlow and FileFlow are exported from the 'bao-bundler/flows' subpath, not the main entry.

CopyRunner

✓ import { CopyRunner } from 'bao-bundler/runners';

✗ import { CopyRunner } from 'bao-bundler';

Runner implementations like CopyRunner are exported from the 'bao-bundler/runners' subpath, not the main entry.

Flow, Runner (types)

✓ import { type Flow, type Runner } from 'bao-bundler';

✗ import { Flow, Runner } from 'bao-bundler';

When importing only types, use 'import type' for clarity and to ensure they are stripped during compilation, though regular 'import' also works for types.

Demonstrates defining a simple asset bundling process using `Project`, `FolderFlow`, `FileFlow`, and `CopyRunner` to copy static assets into a build directory.

import { Project } from 'bao-bundler'; import { FolderFlow, FileFlow } from 'bao-bundler/flows'; import { CopyRunner } from 'bao-bundler/runners'; await new Project('bao-example-project', [ { runner: new CopyRunner(), flow: new FolderFlow({ source: 'assets/images', dest: 'build/images' }) }, { runner: new CopyRunner(), flow: new FolderFlow({ source: 'assets/fonts', dest: 'build/fonts', expand: true }) }, { runner: new CopyRunner(), flow: new FileFlow({ source: 'assets/favicon.ico', dest: 'build/favicon.ico' }) } ]).build(); console.log('Bao Bundler build complete!');

Debug

Known issues

gotchaAs an early-stage project (v0.2.4), Bao Bundler's API is still evolving and may introduce breaking changes in minor or patch releases without strict adherence to semantic versioning until a stable v1.0.0 release.

fix

Refer to the latest documentation and release notes for API changes before upgrading to new minor or patch versions.

affects: <1.0.0

breakingBao Bundler is built exclusively for the Bun runtime. It is not compatible with Node.js or other JavaScript runtimes, and attempting to run it outside Bun will result in errors.

fix

Ensure your project is set up to run with Bun, using `bun install` for dependencies and `bun run <your-script.ts>` for execution.

affects: >=0.1.0

breakingBao Bundler is an ESM-only package. CommonJS `require()` syntax is not supported, and attempts to use it will lead to module resolution errors.

fix

Always use ES module `import` syntax for Bao Bundler and ensure your Bun project is configured for ESM.

affects: >=0.1.0

gotchaControlling log verbosity requires setting the `BAO_VERBOSITY` environment variable (e.g., `DEBUG`, `INFO`, `WARN`, `ERROR`) before executing the Bun script. Default is `DEBUG`, which can be very verbose.

fix

Prefix your Bun command with the desired verbosity: `BAO_VERBOSITY=INFO bun run build.ts`.

affects: >=0.1.0

gotchaThe `source` and `dest` paths within `Flow` configurations are relative to the current working directory from which the `bun run` command is executed, not necessarily relative to the build script's location.

fix

Always verify your working directory or use absolute paths where appropriate. Consider using `path.join(import.meta.dir, 'your-path')` for paths relative to the script.

affects: >=0.1.0

Errors

Common errors & fixes

error: Could not resolve "bao-bundler" from "build.ts"

The `bao-bundler` package is not installed or Bun cannot find it in your `node_modules`.

fix

Run `bun install bao-bundler` to install the package.

ReferenceError: Bun is not defined

The build script is being executed with Node.js or another runtime instead of Bun.

fix

Ensure you are running the script with Bun: `bun run build.ts`.

TypeError: Project is not a constructor

Attempting to use CommonJS `require()` syntax or running in an environment that doesn't fully support ESM.

fix

Ensure you are using ES module `import { Project } from 'bao-bundler';` and executing with Bun.

Error: 'source' path must exist for Flow

A specified `source` path in a `FolderFlow` or `FileFlow` does not exist relative to the current working directory.

fix

Double-check the existence and correctness of the `source` path. Adjust it to be relative to where `bun run` is executed, or use an absolute path.

Upgrade

Version history

0.2.4latest on npm

Audit

Dependencies

typescriptrequiredPeer dependency for TypeScript projects, as Bao Bundler ships types and is designed for TypeScript-first development.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/bao-bundler ↗