Concepts > Root Workspace#

The Root Workspace#

The root workspace is simply a Workspace based on the root package.json of your project.

By default, this is not included in the project's workspaces list, but there are ways to either modify or override the default, and it is always possible to directly reference it explicitly.

Including in the Project's workspaces list#

Including by Default#

You can set the default value to include the root workspace to true in the root configuration defaults or environment variable BW_INCLUDE_ROOT_WORKSPACE_DEFAULT to include the root workspace by default.

Including Explicitly#

Use the CLI global option --include-root to include the root workspace explicitly for a command.

In the API, use the includeRootWorkspace option for createFileSystemProject to include the root workspace explicitly in the project's workspaces.

Referencing the Root Workspace#

There are ways you can always reference the root workspace, regardless of whether it is included in the project's normal workspaces list or not.

For example, in the API, you can always reference the root workspace by using the .rootWorkspace property of a Project.

You can also use the selector defined below:

The Root Selector: @root#

When passing workspace patterns to the CLI for the run-script command, you can use the @root alias to reference the root workspace.

# Run the lint script from the root package.json
bw run lint @root

# Get workspace information for the root workspace
bw workspace-info @root

This can also be used similarly in the API:

import { createFileSystemProject } from "bun-workspaces";

const project = createFileSystemProject();

project.runScriptAcrossWorkspaces({
  workspacePatterns: ["@root"],
  script: "lint",
});

Note that in the off chance you have a workspace named @root, you can more explicitly reference it via name using the workspace pattern specifier "name:@root".