Wurk

Wurk is a lightweight and extensible build system for monorepos.

• Orchestrate tasks across multiple interrelated workspaces.
• Stay flexible and transparent without adding complexity.
• Be declarative and leverage the power of community with custom commands.

Read more about the motivation for this project here.

Prerequisites

• Node.js®
• NPM, PNPM, or Yarn v2+
• Git (recommended but optional)

Getting Started

Install Wurk and any Wurk commands you want as dev dependencies of your root workspace.

npm install --save-dev wurk @wurk/command-run

Note: PNPM and Yarn sometimes prefer using multiple versions of a package. This can lead to Wurk not detecting command plugins. Try running pnpm dedupe wurk or yarn dedupe wurk to resolve this issue.

Run a Wurk command. For example the run command (installed above) runs package.json scripts in each workspace where they exist.

npx wurk run build

(Optional) Install Wurk globally to avoid having to use npx. When wurk is executed, it delegates to the locally installed version, so wurk run build becomes equivalent to npx wurk run build.

npm install --global wurk

(Optional) Delegate root workspace package.json scripts to Wurk.

{
  "scripts": {
    "build": "wurk run build",
    "eslint": "wurk exec eslint src",
    "depcheck": "wurk exec depcheck",
    "test": "wurk build && wurk eslint && wurk depcheck && wurk vitest run"
  }
}

Root workspace package.json scripts can be used as if they were Wurk commands. All Wurk global command line options will be inherited by the Wurk calls used in the scripts.

# Run the test script from the root workspace package.json file.
wurk test -i my-package

# Which is equivalent to running all of the following Wurk commands.
wurk build -i my-package
wurk eslint -i my-package
wurk depcheck -i my-package
wurk vitest run -i my-package

Commands

The following "official" commands are available.

• run: Run package scripts in workspaces.
• exec: Run executables in workspaces.
• vitest: Run Vitest on workspaces.
• version: Set, increment, promote, and conventionally auto generate versions.
• publish: Publish or pack workspace packages.
• list: List workspaces.

Run npm install --save-dev @wurk/command-<name> in your root workspace to install any of these commands.

See the API docs for information on creating your own custom commands.

Options

Wurk has global options for selection, parallelization, logging, etc.

These options are "global" because they are defined by Wurk itself. Commands can also define their own options. In general, global options should precede the command name, and command options should follow the command name. Most commands will allow Wurk to handle global options that follow the command name, but this is not guaranteed.

wurk [global-options] <command> [command-options]

Filter Options

Options which control which workspaces are affected by commands.

• -i, --include <expression> - Include workspaces by name, directory, keyword, etc.
• -e, --exclude <expression> - Exclude workspaces by name, directory, keyword, etc.

The <expression> can be any of the following:

• Workspace Names (glob supported)
  • Examples: my-package or @my-scope/*
• Paths (glob supported)
  • Examples: /packages/my-package or ./packages/*
• Keywords
  • Examples: #foo
• States
  • @public - Public workspaces
  • @private - Private workspaces
  • @published - Published workspaces
  • @unpublished - Unpublished workspaces
  • @dependency - Dependencies of currently included workspaces
  • @dependent - Dependents of currently included workspaces

Path expressions must only use forward slashes (/) as a directory separators, even on Windows. Any backslash (\) characters will be treated as glob escape characters. Paths are always relative to the root workspace directory.

Globs are processed using the minimatch library with default options.

Includes and excludes are processed in order. Includes can re-add workspaces that were previously excluded, and excludes can remove workspaces that were previously included.

If no filters are provided, then all workspaces are included.

Parallelization Options

• --parallel
  • Process all workspaces simultaneously without topological awaiting.
• --stream
  • Process workspaces concurrently with topological awaiting.
• --concurrency <count>
  • Set the number workspaces to process simultaneously when streaming. The default is one greater than the number of CPU cores (cores + 1).
  • This option implies the --stream option.
• --delay-each-workspace <seconds>
  • Delay before starting to process the next workspace. This can be useful for rate limiting, debugging, or working around tool limitations.

By default, workspaces are processed serially (one at a time). This is generally the slowest option, but also the safest.

Logging Options

• --loglevel <level>
  • Set the log level (silent, error, warn, info, notice, verbose, or silly). The default is info.
  • Log level can also be set using the WURK_LOG_LEVEL environment variable. The command line option takes precedence over the environment variable.

Package Managers

Wurk supports NPM, PNPM, and Yarn v2+. The package manager is automatically detected based on the Corepack defined packageManager field in your root package.json file.

If you're not using Corepack, then Wurk will fallback to detecting files and configuration specific to each package manager.

• PNPM: pnpm-workspace.yaml present.
• Yarn: workspaces package field and yarn.lock present.
• NPM: workspaces package field, and NO yarn.lock present.