subrosa

A lightweight CLI tool for managing Node.js monorepos. Existing monorepo tooling tends to be heavyweight and opinionated — subrosa aims to be simple and get out of your way.

How it works

subrosa works by treating packages within your monorepo as peer dependencies of one another. It understands the dependency tree between your packages and handles installation and updates in the correct order automatically.

Setup

In each package that depends on other packages within the monorepo, declare those dependencies as peerDependencies in package.json:

{
  "name": "@acme/ui",
  "peerDependencies": {
    "@acme/utils": "*"
  }
}

subrosa uses your package name prefix (e.g. @acme) to distinguish local monorepo packages from external npm dependencies.

Commands

installAll

Walks the full dependency tree from the current directory and runs npm install on each package in dependency order, ensuring every package is installed before the packages that depend on it.

Run from the root of your monorepo:

npx subrosa installAll --prefix acme --path ./packages

| Option | Description | |--------|-------------| | --prefix | The scope prefix for your monorepo packages (without the @) | | --path | Path to the directory containing your packages, relative to cwd |

update

Packs each local dependency as a tarball and installs it into the current package, in dependency order. This gives you a real install (no symlink side effects) without publishing to npm.

The typical pattern is to hook this into postinstall so local dependencies are always up to date after npm install:

{
  "scripts": {
    "postinstall": "npx subrosa update --prefix acme --path ../../packages"
  }
}

Or call it directly when you want to sync changes from a dependency:

npx subrosa update --prefix acme --path ../../packages

| Option | Description | |--------|-------------| | --prefix | The scope prefix for your monorepo packages (without the @) | | --path | Path to the directory containing your packages, relative to cwd |

Example monorepo layout

my-monorepo/
├── packages/
│   ├── utils/
│   │   └── package.json   (@acme/utils — no local deps)
│   ├── models/
│   │   └── package.json   (@acme/models — no local deps)
│   ├── http/
│   │   └── package.json   (@acme/http — peerDependency: @acme/utils)
│   └── ui/
│       └── package.json   (@acme/ui — peerDependencies: @acme/utils, @acme/models)
└── apps/
    └── web/
        └── package.json   (@acme/web — peerDependencies: @acme/ui, @acme/http)

Running npx subrosa installAll --prefix acme --path ./packages from my-monorepo/ installs packages in dependency order:

1. @acme/utils and @acme/models (no local deps — order between them doesn't matter)
2. @acme/http and @acme/ui (depend on the above)
3. @acme/web (depends on both)

Running npx subrosa update --prefix acme --path ../../packages from my-monorepo/apps/web packs @acme/ui and @acme/http (and their transitive dependencies) as tarballs and installs them into web.