spaceman

Spaceman

Manage monorepo workspaces with a prompt-based CLI

Abstract

Workspaces provide a streamlined workflow to manage multiple packages within a single repository, but require a certain amount of knowledge, configuration and terminal-fu for everyday tasks.

Spaceman makes running complex or multistep tasks easier by wrapping them in prompts, and batching commands on confirmation:

Why read the docs when you can just answer questions?

Spaceman supports NPM, Yarn and Turborepo, with support for PNPM coming in the next release.

Overview

The following tasks are available:

Scripts:

• Run
  Run any root or package script

Packages:

• Install
  Install one or more packages to a target repository
• Uninstall
  Uninstall one or more packages from a target repository
• Update
  Update one or more packages in a target repository
• Reset
  Remove all Node modules-related files in all repos, and reinstall

Workspaces:

• Share
  Make a workspace available for use within another workspace
• Group
  Add a new workspace group
• Add
  Add a new workspace
• Remove
  Remove an existing workspace

Setup

Install the library via NPM:

npm i spaceman --save-dev

Usage

Run the library by typing its name:

spaceman

You should immediately see set of navigable tasks:

? 🚀 Task … 
  Scripts
  ❯ run
  Packages
    install
    uninstall
    update
    reset
  Workspaces
    share
    group
    add
    remove

To run a specific task, pass the task name as a second argument:

spaceman install

Choose a task to run it and view further options:

✔ 🚀 Task · install
? Workspace … 
  apps
  ❯ docs
    web
  packages
    eslint-config-custom
    tsconfig
    ui

The choices should be self-explanatory, but check the documentation below for more detail.

Tasks

Scripts

Run

Run any root or package script:

Script              - type to filter scripts (use spaces for partial matching)

Confirming will run the selected script.

See Settings for configure options.

Packages

Install

Install one or more packages to a target repository:

Workspace           - pick the target workspace to install to
Packages            - type a space-separated list of packages to install
Dependency type     - pick one of normal, development, peer

Confirming will install the new packages.

Uninstall

Uninstall one or more packages from a target repository:

Workspace           - pick the target workspace to uninstall from
Packages            - pick one or more packages to uninstall

Confirming will remove the selected packages.

Update

Update one or more packages in a target repository:

Workspace           - pick the target workspace to update
Packages            - type a space-separated list of packages to install

Confirming will update the selected packages.

Reset

Remove all Node modules-related files in all repos, and reinstall:

Confirm reset?      - confirm to reset repo and workspaces

Confirming will:

• remove all lock files
• remove all node_modules folders
• re-run npm|pnpm|yarn install

Running reset can get you out of tricky situations where workspace installs fail or your IDE reports that seemingly-installed workspaces aren't.

Workspaces

Share

Make a workspace available for use within another workspace:

Source workspace    - pick the source workspace to share
Target workspace(s)  - pick the target workspace(s) to update

Confirming will:

• set the source workspace as a dependency of the target workspace
• run npm|pnpm|yarn install

Group

Add a new workspace group:

Group name          - type a name for the new group

Confirming will:

• create a new top-level folder
• add it to the list of workspaces in package.json
• ask if the user wants to add a new workspace

Add

Add a new workspace:

Workspace group     - pick the target workspace group
Workspace info
 - Workspace        - add name, optional description and `main` file
 - Dependencies     - add optional dependencies
 - Scripts          - add optional scripts

Confirming will:

• create a new workspace folder
• create a private package file
• create a stub "main": "index.ts/js" file with named export
• optionally install dependencies

Remove

Remove an existing workspace:

Workspace           - pick the target workspace
Type to confirm     - type the name of the workspace to confirm deletion

Confirming will:

• remove the dependency from other workspaces
• uninstall workspace dependencies
• remove the workspace folder
• optionally update the repository's workspaces list

Settings

Some of Spaceman's tasks can be configured.

To do this, add a spaceman section to your package.json and include the relevant sections:

{
  "spaceman": {
    "scripts": {
      // regexp to exclude scripts from `run` list, e.g. scripts that start with ~
      "exclude": "^~",
      
      // autocomplete match algorithm; choose between "tight" (default) or "loose" 
      "match": "loose",
    }
  }
}

Some information on the script.match types:

• tight: matches on sequential characters, use spaces to start new match groups, i.e. cli dev
• loose: matches on any character, i.e. clde

Finally...

If you like the package, a tweet is always helpful; be sure to let me know via @dave_stewart.

Thanks!