Concept: Inline Scripts#

Overview#

Normally, a "script" in bun-workspaces references one of the entries found in a workspace's "scripts" field in its package.json file.

However, it's possible to run a one-off shell command from a workspace's directory, an "inline script", such as via bw run "echo 'hello'" --inline in the CLI.

Shell#

Normally, inline scripts are executed using the Bun shell, a bash-like, cross-platform shell, the same as the utility import { $ } from 'bun'.

You can pass --shell=system to use the native shell instead. In POSIX systems (Linux, macOS, etc.), sh -c is called, while in Windows, cmd /d /s /c is called.

You can also set the root config.defaults.shell or environment variable BW_SHELL_DEFAULT to "system" to use the native shell by default.

Examples#

CLI:#

# This will use the Bun shell, 
# unless the root config.defaults.shell
# or process.env.BW_SHELL_DEFAULT is set to "system"
bw run "echo 'hello'" --inline

# Same as the above command
bw run "echo 'hello'" --inline --shell=default

# Explicitly run the Bun shell
bw run "echo 'hello'" --inline --shell=bun

# Run an inline command from the workspace directory using the native shell
bw run "echo 'hello'" --inline --shell=system

API:#

import { createFileSystemProject } from "bun-workspaces";

const project = createFileSystemProject();

// This will use the Bun shell, 
// unless the rootconfig.defaults.shell
// or process.env.BW_SHELL_DEFAULT is set to "system"
project.runWorkspaceScript({
  workspaceNameOrAlias: "my-workspace",
  script: "echo 'this is my inline script'",
  inline: true,
});

project.runWorkspaceScript({
  workspaceNameOrAlias: "my-workspace",
  script: "echo 'this is my inline script'",
  // Takes "bun", "system", or "default", same as the CLI --shell option
  inline: { shell: "system" },
});

Script Name#

Scripts from package.json are named by the key in the "scripts" field.

This is used in output logs and workspace script metadata.

Inline scripts, however, have no name by default, but you can provide a name.

Examples#

CLI:#

# Pass a name for an inline script
bw run "echo 'my script: <scriptName>'" --inline --inline-name=my-inline-script

API:#

project.runWorkspaceScript({
  workspaceNameOrAlias: "my-workspace",
  script: "echo 'this is my inline script'",
  // The name will be empty by default
  inline: true,
});

// Pass a name for an inline script
project.runWorkspaceScript({
  workspaceNameOrAlias: "my-workspace",
  script: "echo 'my script: <scriptName>'",
  inline: { scriptName: "my-inline-script" },
});