Configuration > General#

Configuration is set by JSON. Config files can be written in TypeScript, JavaScript, JSON, or JSONC.

See Root Configuration and Workspace Configuration for more information on the purpose of each field.

Quick Examples#

Root Configuration#

The root configuration is for project-wide settings.

A root configuration in JSON, at path/to/your/project/bw.root.json:

{
  "defaults": {
    "parallelMax": 4,
    "shell": "system",
    "includeRootWorkspace": false
  }
}

A root configuration in TypeScript, at path/to/your/project/bw.root.ts:

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

export default defineRootConfig({
  defaults: {
    parallelMax: 4,
    shell: "system",
    includeRootWorkspace: false
  }
});

Workspace Configuration#

Workspace configurations are defined in the directory of a workspace.

A workspace configuration in JSON, at path/to/project/workspace/bw.workspace.json:

{
  "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"
      ]
    }
  }
}

A workspace configuration in TypeScript, at path/to/project/workspace/bw.workspace.ts:

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

Precedence (Resolution Order)#

Configuration locations#

Configuration is read from the following locations, in order of precedence:

1. bw.<config name>.ts
2. bw.<config name>.js
3. bw.<config name>.jsonc
4. bw.<config name>.json
5. package.json["<key>"]

The first configuration location found will be used.

Value Resolution#

Values related to configuration are resolved in the following order of precedence:

1. An explicit CLI or API argument/option passed to a method/function/command
2. A value provided in a configuration file
3. A value provided via an environment variable, if applicable
4. The generic default value, if applicable