Concept: Workspace Dependencies#

Overview#

Workspaces can depend on other workspaces and import/export code between them. This is a native capability of workspaces in Bun.

bun-workspaces does not perform source code analysis. This keeps determining the graph of workspaces computationally fast and cheap, relying instead on explicit package.json dependencies (using "workspace:*") seen below:

Setting up Dependencies - Example#

For example, this might be some workspace's package.json file, where my-workspace-b depends on my-workspace-a:

my-workspace-a/package.json:

{
  "name": "my-workspace-a",
  "main": "index.ts"
}

my-workspace-b/package.json:

{
  "name": "my-workspace-b",
  "dependencies": {
    "my-workspace-a": "workspace:*"
  }
}

Code in my-workspace-a can then import code from my-workspace-b like any other dependency.

my-workspace-a/index.ts:

export const myFunction = () => {
  console.log("Hello from my-workspace-a");
}

my-workspace-b/index.ts:

import { myFunction } from "my-workspace-a";

myFunction();

Workspace Dependency Rules#

You can set rules to allow or deny other workspaces as dependencies in a workspace's configuration, set by workspace patterns.

Use allowPatterns to define which dependencies are permitted or denyPatterns to forbid specific ones. When both are present, denyPatterns will further filter the subset already permitted by allowPatterns.

For example, you may disallow dependencies with the tag "backend" for a frontend workspace with denyPatterns: ["tag:backend"].

Running Scripts in Dependency Order#

When running scripts via the CLI or API, workspaces can be run in dependency order.

This means that a workspace's script will wait until any workspaces it depends on have completed. This is similar to how Bun's --filter flag works, though for bun-workspaces, this behavior is opt-in.

This can be useful in situations where one workspace depends on another workspace's output, such as a build script's output.

CLI Example#

bw run my-script --dep-order

# Run all scripts even if a dependency fails
bw run my-script --dep-order --ignore-dep-failure

API Example#

import { createFileSystemProject } from "bun-workspaces";

const project = createFileSystemProject();

project.runScriptAcrossWorkspaces({
  script: "my-script",
  dependencyOrder: true,
  ignoreDependencyFailure: true,
});