oao 📦

A Yarn-based, opinionated monorepo management tool.

Why? ✨

• Works with yarn, hence (relatively) fast!.
• Simple to use and extend (hope so!).
• Provides a number of monorepo workflow enhancers: installing all dependencies, adding/removing/upgrading sub-package dependencies, validating version numbers, determining updated sub-packages, publishing everything at once, updating the changelog, etc.
• Supports yarn workspaces, optimising the monorepo dependency tree as a whole and simplifying bootstrap as well as dependency add/upgrade/remove.
• Prevents some typical publish errors (using a non-master branch, uncommitted/non-pulled changes).
• Runs a command or package.json script on all sub-packages, serially or in parallel, optionally following the inverse dependency tree.
• Provides an easy-to-read, detailed status overview.
• Support for non-monorepo publishing: benefit from oao's pre-publish checks, tagging, version selection, changelog updates, etc. also in your single-package, non-monorepos.

Assumptions 💭

As stated in the tagline, oao is somewhat opinionated and makes the following assumptions on your monorepo:

• It uses a synchronized versioning scheme. In other words: a master version is configured in the root-level package.json, and sub-packages will be in sync with that version (whenever they are updated). Some sub-packages can be left behind version-wise if they're not updated, but they'll jump to the master version when they get some love.
• You use git for version control and have already initialised your repo.
• Git tags are used for releases (and only for releases), and follow semver: v0.1.3, v2.3.5, v3.1.0-rc.1 and so on.
• Some sub-packages may be public, others private (flagged "private": true in package.json). OK, no assumption here: rest assured that no private sub-packages will be published by mistake.

Installation

If yarn is not installed in your system, please install it first. If you want to use yarn workspaces (available since yarn 0.28), enable them by running yarn config set workspaces-experimental true and configure the following in your monorepo package.json (replace the glob patterns for your subpackages/workspaces as needed):

"workspaces": [
  "packages/*"
]

Add oao to your development dependencies (use the -W flag to avoid Yarn's warning when installing dependencies on the monorepo root):

$ yarn add oao --dev -W

Usage

To see all CLI options, run oao --help:

Usage: oao [options] [command]

Options:

  -V, --version  output the version number
  -h, --help     output usage information

Commands:

  status [options]                               Show an overview of the monorepo status
  bootstrap [options]                            Install external dependencies and create internal links
  clean [options]                                Delete all node_modules directories from sub-packages and the root package
  add [options]        Add dependencies to a sub-package
  remove [options]     Remove dependencies from a sub-package
  upgrade [options]  [packages...]  Upgrade some/all dependencies of a package
  outdated [options]                             Check for outdated dependencies
  prepublish [options]                           Prepare for a release: validate versions, copy READMEs and package.json attrs
  publish [options]                              Publish updated sub-packages
  reset-all-versions [options]          Reset all versions (incl. monorepo package) to the specified one
  all [options]                         Run a given command on all sub-packages
  run-script [options]                  Run a given script on all sub-packages

You can also get help from particular commands, which may have additional options, e.g. oao publish --help:

Usage: publish [options]

Publish all (non-private) sub-packages

Options:

-s --src                                            glob pattern for sub-package paths [packages/*] (default: "packages/*")
-i --ignore-src                                     glob pattern for sub-package paths that should be ignored
-l --link                                          regex pattern for dependencies that should be linked, not installed
--single                                                  no subpackages, just the root one
--relative-time                                           shorten log dates
--no-master                                               allow publishing from a non-master or non-main branch
--no-check-uncommitted                                    skip uncommitted check
--no-check-unpulled                                       skip unpulled check
--no-checks                                               skip all pre-publish checks
--no-bump                                                 do not increment version numbers (also disables git commit)
--no-confirm                                              do not ask for confirmation before publishing
--no-git-commit                                           skip the commit-tag-push step before publishing
--no-npm-publish                                          skip the npm publish step
--new-version                                    use this version for publishing, instead of asking
--increment-version-by   increment version by this, instead of asking
--publish-tag                                        publish with a custom tag (instead of `latest`)
--changelog-path