bun-workspacesbun-workspaces
Latest: v1.0.0
CLI
API
Config
Concepts

bun-workspaces

A monorepo management tool on top
of native Bun workspaces

  • Works right away, with no boilerplate required 🍔🍴
  • Get metadata about your monorepo 🤖
  • Run package.json scripts across workspaces 📋
  • Run inline Bun Shell scripts from your workspaces 🐚

This is a tool to help manage a Bun monorepo, offering features beyond what Bun's --filter feature can do. It can be used to get a variety of metadata about your project and run scripts across your workspaces with advanced control.

To get started, all you need is a repo using Bun's workspaces feature for nested JavaScript/TypeScript packages.

This package is unopinionated and works with any project structure you want. Think of this as a power suit you can snap onto native workspaces, rather than whole new monorepo framework.

Start running some CLI commands right away in your repo, or take full advantage of the scripting API and its features.


What's New

Notable recent updates 📦

  • Version 1.0 is now here after the initial alpha! 🍔🍔👁️🍔🍔
  • New CLI output style for running scripts. --no-prefix is now deprecated in favor of --output-style=plain.
  • You can now run scripts in dependency order, similar to Bun's --filter behavior. See more on workspace dependencies.
  • More advanced workspace patterns can be used to select workspaces, such as by path.
  • It's now possible to include or reference a project's root workspace.
  • Configuration updates: Added new project root configuration to set defaults, and JSONC is supported for configuration files.
  • The Bun Shell is now used by default to run inline scripts, with the option to use the system shell.
  • Increased support for Windows users.

Quick Start

See the CLI Quick Start and API Quick Start for starting examples. See the Glossary for more fundamental concepts.

Installation

Required Bun version: ^1.2.0

You can install the package in your project or simply use bunx bun-workspaces to immediately use the latest version of the CLI. Installation is required to use the API.

# Install to use the API and/or lock your CLI version for your project
bun add --dev bun-workspaces

# Start using the CLI with or without the installation step
bunx bun-workspaces --help

If you use the CLI frequently, you might consider using a shell alias.

# Add this to .bashrc, .zshrc, or similar 
# to make it available by default in your shell
alias bw="bunx bun-workspaces"

Examples in these docs will use the alias bw for bunx bun-workspaces for brevity.

Note that you need to run bun install in your project for bun-workspaces to find your project's workspaces. This is because it reads bun.lock. This also means that if you update your workspaces, such as changing their name, you must run bun install for the change to reflect.


bun-workspaces is independent from the Bun project and is not affiliated with or endorsed by Anthropic. This project aims to enhance the experience of Bun for its users.

Developed By: