⚠️ Deprecated Package

bun-workspaces has been deprecated and is now developed as pacwich, which supports Bun, npm, and pnpm workspaces, with a mostly backwards compatible CLI and API. Users can expect little to no disruption beyond the package name change and config file name changes.

A full migration guide covering all differences between the packages is available at https://pacwich.dev/intro/bun-workspaces-migration

Installation docs are available at https://pacwich.dev/intro/getting-started

You can also instruct an LLM agent to read https://pacwich.dev/intro/bun-workspaces-migration/index.md to assist with migration.

Read the launch blog post about the motivations and development strategy.

bun-workspaces will not receive further releases save for critical security patches, if necessary. This website will stay up at least through 2026. Once decommissioned, documentation will be consolidated to the package README.

bun-workspacesbun-workspaces
Latest: v1.12.0
Blog
CLI
API
Config
Concepts
AI
Blog

Concept: Workspace Patterns

Overview

Workspace patterns are used to match workspaces when running commands such as run-script or list-workspaces, and they are also used in some configuration options.

Negation is supported by prefixing any pattern with not: or !, the former suggested to avoid shell operator issues. These exclude workspaces from any other patterns provided.

Regular expressions are supported by prefixing any pattern value with re:.

Workspace Pattern Syntax:
[not:][(name|alias|path|tag):][re:]<value>

Quick Examples:

"my-name-or-alias" # matches workspace name or alias
"my-name-pattern-*" # matches workspace names only by wildcard
"alias:my-alias-pattern-*" # matches workspace aliases by wildcard
"path:packages/**/*" # matches workspace paths by glob
"tag:my-tag" # matches workspaces with tag
"not:my-name-or-alias" # excludes workspace name or alias
"not:tag:my-tag-pattern-*" # excludes workspace tag matching wildcard
"re:^my-regex-pattern$" # matches workspace name or alias by regex
"not:tag:re:^my-tag-regex-pattern$" # excludes workspace tag by regex
"@root" # matches the root workspace

The @root special selector matches the root workspace.

Default Matching

By default, normal strings match a workspace name or alias.

However, if a wildcard is provided, it will only match against workspace names, to prevent ambiguity.

bw run lint my-name-or-alias "my-name-pattern-*"

See below for how you can use wildcards with aliases.

Matching Specifiers

Matching specifiers give you more control and options for how you match workspaces.

Name

Match by the workspace name (from package.json). Accepts wildcards.

bw ls name:my-workspace "name:my-workspace-*"
bw run lint "name:my-workspace-*"

Alias

Match by the workspace alias. Accepts wildcards.

bw ls "alias:my-alias-*"
bw run lint "alias:my-alias-b"

Path

Match by the relative workspace path, with glob syntax supported.

bw ls "path:packages/**/*"
bw run lint "path:packages/**/*"

Tag

Match workspaces that have the given tag. Tags are defined in a workspace's configuration file.

bw ls "tag:my-tag"
bw run lint "tag:my-tag-pattern-*"

Negation

You can negate a pattern by prefixing it with not: or !. not: is preferred over ! to avoid shell operator issues. These exclude workspaces from any other patterns provided.

Negated patterns are removed from the set of matched workspaces, so a "all workspaces except my-workspace" requires two patterns: "*" and "not:my-workspace".

# All workspaces except the name or alias "my-name-or-alias"
bw ls "*" "not:my-name-or-alias"

# All workspaces except those with the tag "my-tag"
bw ls "*" "not:tag:my-tag"

Regex Modifier

You can use the re: modifier to match patterns using regular expressions.

# All workspaces with names that start with "app-"
bw ls "re:^app-.*"

# All workspaces except those with tags that start with "my-tag-"
bw ls "*" "not:tag:re:^my-tag-.*"

In the API

These same matching patterns can be used in the API.

import { createFileSystemProject } from "bun-workspaces";

const project = createFileSystemProject();

project.findWorkspacesByPattern(
  "my-name-or-alias",
  "name:my-workspace-*", 
  "alias:my-alias-*", 
  "path:packages/**/*",
  "tag:my-tag",
);

project.runScriptAcrossWorkspaces({
  workspacePatterns: [
    "my-name-or-alias",
    "name:my-workspace-*",
    "alias:my-alias-*",
    "path:packages/**/*",
    "tag:my-tag",
  ],
  script: "bun lint",
});
ON THIS PAGE