Configuration > Workspace#

Workspace Configuration#

The optional configuration for a workspace is defined in a file such as bw.workspace.json in its directory or in its package.json file.

You can set a workspace's alias(es), the order sequence for its scripts, workspace tags (see below), and workspace dependency rules (see below).

You can also use the root config to set workspace configs in bulk by using workspace patterns. See the workspace pattern configs page for more information.

Tags#

Tags are simple strings that can be used to group workspaces together. They can be used in workspace patterns.

Workspace Dependency Rules#

Using the rules.workspaceDependencies field, you can define rules for which workspaces are allowed to be dependencies, using allowPatterns, denyPatterns, or both.

Workspace patterns are used to match workspaces.

allowPatterns defines the permitted subset of dependencies. denyPatterns forbids specific dependencies. When both are present, denyPatterns further filters within the subset permitted by allowPatterns. You can also use negated workspace patterns to exclude workspaces from the allowed or denied list.

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

Type Definition#

{
  // Must be unique across other aliases and workspace names
  alias?: string | string[],
  // Tags can be used to group workspaces together
  tags?: string[],
  scripts?: {
    [script: string]: {
      // Optional sorting order for running scripts
      order?: number
    }
  },
  rules?: {
    workspaceDependencies?: {
      // Use workspace patterns to match workspaces to allow as dependencies
      allowPatterns?: string[],
      // Workspace patterns to forbid as dependencies.
      // When combined with allowPatterns, filters within that allowed subset.
      denyPatterns?: string[]
    }
  }
}

Examples:#

1. TypeScript/JavaScript file#

path/to/your/workspace/bw.workspace.ts or path/to/your/workspace/bw.workspace.js

import { defineWorkspaceConfig } from "bun-workspaces/config";

export default defineWorkspaceConfig({
  alias: "myApp",
  tags: [
    "my-tag"
  ],
  scripts: {
    start: {
      order: 10
    },
    test: {
      order: 20
    }
  },
  rules: {
    workspaceDependencies: {
      allowPatterns: [
        "my-workspace-a",
        "tag:my-tag",
        "path:my-path/**/*",
        "not:tag:my-excluded-tag"
      ]
    }
  }
});

Merge Utility#

You can use the mergeWorkspaceConfig function to merge multiple workspace configurations left to right, with each subsequent config taking precedence. Objects are merged deeply, and array items are concatenated while keeping items unique.

import { mergeWorkspaceConfig } from "bun-workspaces/config";

export default mergeWorkspaceConfig(
  { alias: "a", tags: ["x"] },
  { alias: "b", scripts: { build: { order: 1 } } },
  // Factory function receives the accumulated config up to that point
  (prevConfig) => ({ tags: ["y"] }),
);

2. JSON/JSONC file#

path/to/your/workspace/bw.workspace.json or path/to/your/workspace/bw.workspace.jsonc

{
  "alias": "myApp",
  "tags": [
    "my-tag"
  ],
  "scripts": {
    "start": {
      "order": 10
    },
    "test": {
      "order": 20
    }
  },
  "rules": {
    "workspaceDependencies": {
      "allowPatterns": [
        "my-workspace-a",
        "tag:my-tag",
        "path:my-path/**/*",
        "not:tag:my-excluded-tag"
      ]
    }
  }
}

3. package.json#

path/to/your/workspace/package.json

{
  "name": "@my-organization/my-application",
  "description": "My app",
  "version": "1.0.0",
  "bw": {
    "alias": "myApp",
    "tags": [
      "my-tag"
    ],
    "scripts": {
      "start": {
        "order": 10
      },
      "test": {
        "order": 20
      }
    },
    "rules": {
      "workspaceDependencies": {
        "allowPatterns": [
          "my-workspace-a",
          "tag:my-tag",
          "path:my-path/**/*",
          "not:tag:my-excluded-tag"
        ]
      }
    }
  }
}