{"id":12874,"library":"bao-bundler","title":"Bao Bundler","description":"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.","status":"active","version":"0.2.4","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","bun","bundler","assets","typescript"],"install":[{"cmd":"npm install bao-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add bao-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add bao-bundler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for TypeScript projects, as Bao Bundler ships types and is designed for TypeScript-first development.","package":"typescript","optional":false}],"imports":[{"note":"Bao Bundler is an ESM-only package, designed for Bun. CommonJS 'require' is not supported.","wrong":"const Project = require('bao-bundler').Project;","symbol":"Project","correct":"import { Project } from 'bao-bundler';"},{"note":"Flow implementations like FolderFlow and FileFlow are exported from the 'bao-bundler/flows' subpath, not the main entry.","wrong":"import { FolderFlow } from 'bao-bundler';","symbol":"FolderFlow, FileFlow","correct":"import { FolderFlow, FileFlow } from 'bao-bundler/flows';"},{"note":"Runner implementations like CopyRunner are exported from the 'bao-bundler/runners' subpath, not the main entry.","wrong":"import { CopyRunner } from 'bao-bundler';","symbol":"CopyRunner","correct":"import { CopyRunner } from 'bao-bundler/runners';"},{"note":"When importing only types, use 'import type' for clarity and to ensure they are stripped during compilation, though regular 'import' also works for types.","wrong":"import { Flow, Runner } from 'bao-bundler';","symbol":"Flow, Runner (types)","correct":"import { type Flow, type Runner } from 'bao-bundler';"}],"quickstart":{"code":"import { Project } from 'bao-bundler';\nimport { FolderFlow, FileFlow } from 'bao-bundler/flows';\nimport { CopyRunner } from 'bao-bundler/runners';\n\nawait new Project('bao-example-project', [\n  {\n    runner: new CopyRunner(),\n    flow: new FolderFlow({\n      source: 'assets/images',\n      dest: 'build/images'\n    })\n  },\n  {\n    runner: new CopyRunner(),\n    flow: new FolderFlow({\n      source: 'assets/fonts',\n      dest: 'build/fonts',\n      expand: true\n    })\n  },\n  {\n    runner: new CopyRunner(),\n    flow: new FileFlow({\n      source: 'assets/favicon.ico',\n      dest: 'build/favicon.ico'\n    })\n  }\n]).build();\n\nconsole.log('Bao Bundler build complete!');","lang":"typescript","description":"Demonstrates defining a simple asset bundling process using `Project`, `FolderFlow`, `FileFlow`, and `CopyRunner` to copy static assets into a build directory."},"warnings":[{"fix":"Refer to the latest documentation and release notes for API changes before upgrading to new minor or patch versions.","message":"As 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.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Ensure your project is set up to run with Bun, using `bun install` for dependencies and `bun run <your-script.ts>` for execution.","message":"Bao 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.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Always use ES module `import` syntax for Bao Bundler and ensure your Bun project is configured for ESM.","message":"Bao Bundler is an ESM-only package. CommonJS `require()` syntax is not supported, and attempts to use it will lead to module resolution errors.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Prefix your Bun command with the desired verbosity: `BAO_VERBOSITY=INFO bun run build.ts`.","message":"Controlling 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `bun install bao-bundler` to install the package.","cause":"The `bao-bundler` package is not installed or Bun cannot find it in your `node_modules`.","error":"error: Could not resolve \"bao-bundler\" from \"build.ts\""},{"fix":"Ensure you are running the script with Bun: `bun run build.ts`.","cause":"The build script is being executed with Node.js or another runtime instead of Bun.","error":"ReferenceError: Bun is not defined"},{"fix":"Ensure you are using ES module `import { Project } from 'bao-bundler';` and executing with Bun.","cause":"Attempting to use CommonJS `require()` syntax or running in an environment that doesn't fully support ESM.","error":"TypeError: Project is not a constructor"},{"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.","cause":"A specified `source` path in a `FolderFlow` or `FileFlow` does not exist relative to the current working directory.","error":"Error: 'source' path must exist for Flow"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null}