Configuration: Root Config File#

The optional root configuration is the general configuration for a project at a file such as bw.root.json or in its package.json file.

Type Definition#

type RootConfig = {
  defaults?: {
    // The default maximum number of scripts that can run in parallel
    parallelMax?: number | `${number}%` | "auto" | "unbounded" | "default",
    // The default shell to use for inline scripts
    shell?: "bun" | "system" | "default",
    // Whether to include the root workspace in the workspace list
    includeRootWorkspace?: boolean,
    // The default git base ref for affected workspace resolution (default: main)
    affectedBaseRef?: string
  },
  // Apply workspace configs in bulk by using workspace patterns
  workspacePatternConfigs?: {
    patterns?: string[],
    config?: WorkspaceConfig | WorkspacePatternConfigFactory
  }[]
}

Defaults#

The values in config.defaults can also be set by environment variables. Configuration values take precedence over environment variables.

• config.defaults.parallelMax: The parallel max value
• config.defaults.shell: The shell option for inline scripts
• config.defaults.includeRootWorkspace: Whether to include the root workspace in the project's workspaces list
• config.defaults.affectedBaseRef: The default git base ref for affected workspaces resolution (this is main when not overridden)

Workspace Pattern Configs#

You can set workspace configs in bulk by using workspace patterns in workspacePatternConfigs.

See the workspace pattern configs page for more information.

Examples:#

1. TypeScript/JavaScript file#

path/to/your/project/bw.root.ts or path/to/your/project/bw.root.js

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

export default defineRootConfig({
  defaults: {
    parallelMax: 4,
    shell: "system",
    includeRootWorkspace: false,
    affectedBaseRef: "my-branch"
  },
  workspacePatternConfigs: [
    {
      patterns: [
        "path:libraries/frontend/**/*"
      ],
      config: {
        tags: [
          "frontend",
          "library"
        ]
      }
    }
  ]
});

mergeRootConfig Utility#

You can use the mergeRootConfig function to merge multiple root configurations left to right, with each subsequent config taking precedence. Objects are merged deeply.

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

export default mergeRootConfig(
  { defaults: { parallelMax: 4 } },
  { defaults: { shell: "system" } },
  // Factory function receives the accumulated config up to that point
  (prevConfig) => ({ defaults: { includeRootWorkspace: true } }),
);

2. JSON/JSONC file#

path/to/your/project/bw.root.json or path/to/your/project/bw.root.jsonc

{
  "defaults": {
    "parallelMax": 4,
    "shell": "system",
    "includeRootWorkspace": false,
    "affectedBaseRef": "my-branch"
  },
  "workspacePatternConfigs": [
    {
      "patterns": [
        "path:libraries/frontend/**/*"
      ],
      "config": {
        "tags": [
          "frontend",
          "library"
        ]
      }
    }
  ]
}

3. package.json#

path/to/your/project/package.json

{
  "name": "my-project",
  "description": "My project root",
  "workspaces": [
    "packages/*"
  ],
  "bw-root": {
    "defaults": {
      "parallelMax": "50%",
      "shell": "system",
      "includeRootWorkspace": true,
      "affectedBaseRef": "my-branch"
    }
  }
}