Skip to content

Workspace commands

Your monorepo’s Workspaces may end up having unique needs that differ from other Workspaces. When this occurs, you may want to have commands that are specific to an individual Workspace. There are two ways to configure oneRepo to enable Workspace-specific commands.

Workspaces can have custom commands that work identically to commands at the root of your repository. The configuration value enables a directory within each Workspace of your application, if present, to contain command files that will automatically be included in the one CLI when invoked.

By default, the is set to 'commands'.

import type { Config } from 'onerepo';
export default {
commands: {
directory: 'commands',
} satisfies Config;

This setting will automatically enable each Workspace to add command files:

  • Directoryapps
    • Directorypublic-app
      • Directorycommands/
        • start.ts # one ws public-app start
        • build.ts
    • Directoryprivate-app
      • Directorycommands/
        • start.ts # one ws private-app start
        • build.ts

And in turn, our custom commands will be exposed on the one workspace (or one ws alias, for short) command:

Run public-app commands.
# Run the `start` command
one workspace public-app start
# Run the `build` command
one workspace public-app build
Build private-app commands.
one workspace private-app build
# ↑ Equivalent to ↓
one ws private-app build

Read the writing commands documentation for a tutorial and in-depth information on the structure, shape, and strategies for commands.

Alternatively, for quick access to third-party commands that don’t require extra configuration, we can configure passthrough commands in Workspace configuration files:

export default {
commands: {
passthrough: {
start: { command: 'astro dev', description: 'Start the Astro dev server.' },
build: { command: 'astro build', description: 'Build the app using Astro.' },
} satisfies WorkspaceConfig;

Some third-party spackages expose executables for running servers and quick helpers that use configuration files instead of command-line flags, like Astro and Vite. These types of commands are great candidates for passthroughs.

By enabling the passthrough using the above configuration for public-app, we add two commands to the Workspace: start and build and can be called with either form of the workspace command using one workspace … or the alias one ws …:

Run the Astro dev server.
one workspace public-app start
# ↑ Equivalent to ↓
one ws public-app start
Build the app using Astro.
one workspace public-app build
# ↑ Equivalent to ↓
one ws public-app build

If you need a little bit more and want to pass arguments through to the underlying command (in this case astro …), include any extra argument flags after the CLI parser stop point (--):

Pass arguments to Astro
one workspace public app start -- --port=8000 --open

Aliases: one ws

Run commands within individual Workspaces.

Terminal window
one workspace <workspace-name> <commands...> [options...] -- [passthrough...]

This enables running both custom commands as defined via the configuration option within each Workspace as well as commands.passthrough aliases.

Arguments for passthrough commands meant for the underlying command must be sent after --.

commandstringCommand to run.
workspace-namestringThe name or alias of a Workspace.