Concept: Workspace Script Metadata#

Overview#

When running scripts via the API or CLI, metadata is available via either environment variables within your scripts or interpolation in an inline script or appended args.

The environment variables allow scripts to introspect metadata about the project, workspace, and script info to get context about its execution by bun-workspaces.

This same metadata can be referenced within inline script commands and/or appended script args.

Examples#

Interpolation via CLI:#

In this command, all workspaces will run the same my-script.ts file found at the project root, thanks to using <projectPath> to interpolate the project root's path, and the workspace name and path will be passed to the script as arguments.

bw run "bun <projectPath>/my-script.ts" --inline \
  --inline-name="my-script-name" \
  --args="<workspaceName> <workspacePath>"

The script itself could use metadata from the environment variables to dynamically change its behavior based on the workspace context passed to it:

Interpolation via API:#

The same as the above CLI example using the TypeScript API:

import { createFileSystemProject } from 'bun-workspaces';

const project = createFileSystemProject();

project.runScriptAcrossWorkspaces({
  script: "bun <projectPath>/my-script.ts",
  args: "<workspaceName> <workspacePath>",
  inline: { scriptName: "my-script-name" },
});

Accessing in a script via environment variables#

You can access metadata from within a script that was invoked via bun-workspaces via environment variables directly or the getWorkspaceScriptMetadata helper.

import { getWorkspaceScriptMetadata } from 'bun-workspaces/script';

// Use the helper within a script that was invoked via bun-workspaces
const projectPath = getWorkspaceScriptMetadata("projectPath");
const projectName = getWorkspaceScriptMetadata("projectName");
const workspaceName = getWorkspaceScriptMetadata("workspaceName");
const workspacePath = getWorkspaceScriptMetadata("workspacePath");
const workspaceRelativePath = getWorkspaceScriptMetadata("workspaceRelativePath");
const scriptName = getWorkspaceScriptMetadata("scriptName");

// Access via plain environment variables (same values as above)
console.log(process.env.BW_PROJECT_PATH);
console.log(process.env.BW_PROJECT_NAME);
console.log(process.env.BW_WORKSPACE_NAME);
console.log(process.env.BW_WORKSPACE_PATH);
console.log(process.env.BW_WORKSPACE_RELATIVE_PATH);
console.log(process.env.BW_SCRIPT_NAME);

Available Metadata#

Project Path#

The absolute path to the project root.

In inline scripts and args: <projectPath>
Environment variable: BW_PROJECT_PATH

Project Name#

The name of the project (as in its package.json "name" field).

In inline scripts and args: <projectName>
Environment variable: BW_PROJECT_NAME

Workspace Name#

The name of the workspace (as in its package.json "name" field).

In inline scripts and args: <workspaceName>
Environment variable: BW_WORKSPACE_NAME

Workspace Path#

The absolute path to the workspace.

In inline scripts and args: <workspacePath>
Environment variable: BW_WORKSPACE_PATH

Workspace Relative Path#

The relative path to the workspace from the project root.

In inline scripts and args: <workspaceRelativePath>
Environment variable: BW_WORKSPACE_RELATIVE_PATH

Script Name#

The name of the script. This is an empty string when running as an inline script, unless a script name is explicitly provided.

In inline scripts and args: <scriptName>
Environment variable: BW_SCRIPT_NAME