bun-workspaces
A monorepo tool that enhances native Bun workspaces
- 🍽️ Works right away, with no boilerplate required 🍽️
- 🤖 Get rich metadata about your monorepo 🤖
- 🎻 Orchestrate your workspaces'
package.jsonscripts 🎻 - 🐚 Run one-off Bun Shell commands in your workspaces 🐚
- 🎁 Use with Bun as your package manager for Node projects 🎁
- 🕸️ Determine affected workspaces based on changed files 🕸️
- 🛠️ Use the MCP server to make your AI tooling aware of
bun-workspacesand its documentation resources! 🛠️
To get started, all you need is a repo using Bun's workspaces feature for nested JavaScript/TypeScript packages. This adds enhanced features on top of plain workspaces.
Start running some CLI commands right away in your repo, or take full advantage of the TypeScript API and its features.
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.
What's New
Notable recent updates 📦
- v1.9: New features for affected workspaces based on changed files. See the Affected Workspaces concept for more details or the release blog post.
- v1.6: Workspace configs can be set in bulk via workspace patterns in the root config's workspace pattern configs.
- See the recent blog post on features up to v1.5, including dependency rules, tags, and the MCP server.
- The
bun-workspacesBlog is now live! The first post covers the v1 release. - Version 1.0 is now here after the initial alpha! 🍔🍔👁️🍔🍔
- New CLI output style for running scripts.
--no-prefixis now deprecated in favor of--output-style=plain. - You can now run scripts in dependency order, similar to Bun's
--filterbehavior. See more on workspace dependencies.
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 --helpIf 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.
Stale Workspace Data
Note that you need to run bun install in your project for
bun-workspaces to find your project's workspaces, and you
likely must run this again after you've updated your workspaces, such as
changing a name or adding/removing one. This is because bun.lock
lists workspaces and is used as the source of truth.
Why not a global install?
It's possible to add bw to your shell's PATH to make it available globally via bun add -g bun-workspaces.
However, bunx is recommended instead in order to ensure version consistency within projects. With the
alias using bunx above, bw will use the locked version of bun-workspaces for a project that installed it.
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.