Glossary#

Learn some of the basic terms and primitives of bun-workspaces here.

Terms#

Project#

This is typically the same as the root of your git repository for your monorepo. This is where your top-level package.json file is located, which contains the "workspaces" field.

See Bun's documentation for more information on setting up workspaces via package.json.

Workspace#

This is the same conceptually as a workspace in Bun. bun-workspaces simply allows enriching and working with workspaces in various ways.

A nested package within a project. The root of a workspace is always a nested directory within the project that contains its own package.json file.

A workspace's directory must be matched by the globs in the project root package.json's "workspaces" field.

Script#

In the context of bun-workspaces, a "script" generally refers to an entry in the "scripts" field in a workspace's package.json file by default.

However, bun-workspaces also supports running "inline scripts", one-off shell commands executed from a respective workspace's directory.

Terms in Action#

This is a minimal example of a project structure.

Placing workspaces in the packages/ directory is a common convention but not required.

my-project/
├── package.json
└── packages/
    ├── my-workspace-a/
    │   └── package.json
    └── my-workspace-b/
        └── package.json

The root package.json:

{
  "name": "my-project",
  "workspaces": [
    "packages/*"
  ]
}

The workspaces' package.json files:

{
  "name": "my-workspace-a",
  "scripts": {
    "my-script": "echo 'My script for workspace A'"
  }
}

{
  "name": "my-workspace-b",
  "scripts": {
    "my-script": "echo 'My script for workspace B'"
  }
}