Configuration > Root#

Project Root Configuration#

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
  },
  // 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. Defaults provided in the configuration take precedence over environment variables.

You can set defaults for the parallel max value, the shell option for inline scripts, and whether to include the root workspace in the project's workspaces list.

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
  }
});

Merge 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
  }
}

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
    }
  }
}