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.

Custom commands

Section titled Custom commands

Workspaces can have custom commands that work identically to commands at the root of your repository. The RootConfig.commands.directory 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 commands.directory is set to 'commands'.

onerepo.config.ts

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.

Passthrough commands

Section titled Passthrough commands

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

apps/public-app/onerepo.config.ts

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.

Danger

This configuration is a shortcut for quick one-offs with little to no extra options necessary. Avoid over-using this configuration to avoid script overload pitfalls.

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

Command usage

Section titled Command usage

one workspace

Section titled one workspace

Aliases: one ws

Run commands within individual Workspaces.

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

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

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

Positional	Type	Description
command	string	Command to run.
workspace-name	string	The name or alias of a Workspace.