Concepts > Script Runtime Metadata#

When running scripts via the API or CLI, runtime metadata is available to be used in the script, which can be interpolated in an inline script or appended args, or it can be read from environment variables.

Examples#

This example shows various uses of the runtime metadata for running the same file from all workspaces via an inline script, using the metadata in the script itself via environment variables, the inline command, and the --args (-a) passed.

// Contents of my-script.ts (in project root)

// All metadata is available as environment variables for use within a script
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);

CLI:#

bw run "bun <projectPath>/my-script.ts" -i -I "my-script-name" -a "<scriptName>"

API:#

import { createFileSystemProject } from 'bun-workspaces';

const project = createFileSystemProject({
  rootDirectory: ".",
});

project.runScriptAcrossWorkspaces({
  workspacePatterns: ["*"],
  script: "bun <projectPath>/my-script.ts",
  args: "<scriptName>",
  inline: { scriptName: "my-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