Manage monorepo workspaces with a prompt-based CLI
Monorepos provide a way to manage multiple self-contained applications and packages within a single codebase:
- my-awesome-app
- apps
| - backend
| | - package.json
| - frontend
| | - package.json
- packages
| - tools
| | - package.json
| - utils
| - package.json
package.json
Workspaces are the building blocks of monorepos, but require a certain amount of knowledge, configuration and terminal-fu for everyday tasks.
Spaceman simplifies complex or multistep workspace tasks by presenting them as prompts, and batching commands on confirmation:
Why read the docs when you can just answer questions?
Spaceman supports NPM and Yarn with support for PNPM coming in the next release. It also plays nice with monorepo tools such as Turborepo, Lerna and Rush.
The following tasks are available:
Scripts
- Run
Run any root or package script
Packages
- Install
Install one or more packages to a workspace - Uninstall
Uninstall one or more packages from a workspace - Update
Update one or more packages in a workspace - Reset
Remove all Node modules-related files in the root and all workspaces, and reinstall
Workspaces
- Share
Make a workspace available for use within another workspace - Group
Add a new top-level workspace group - Add
Add a new workspace - Remove
Remove an existing workspace
Install the library via NPM:
npm i spaceman --save-dev
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.
Run any root or package script:
Script - type to filter scripts (use spaces for partial matching)
Confirming will run the selected script.
See Configuration for additional options.
Install one or more packages to a workspace:
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 one or more packages from a workspace:
Workspace - pick the target workspace to uninstall from
Packages - pick one or more packages to uninstall
Confirming will remove the selected packages.
Update one or more packages in a workspace:
Workspace - pick the target workspace to update
Packages - type a space-separated list of packages to install
Confirming will update the selected packages.
Remove all Node modules-related files in the root and all workspaces, and reinstall:
Confirm reset? - confirm to reset root 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.
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
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 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 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
workspaces
list
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
If you like the package, a tweet is always helpful; be sure to let me know via @dave_stewart.
Thanks!