# oao :package: [![Build Status](https://travis-ci.org/guigrpa/oao.svg?branch=master)](https://travis-ci.org/guigrpa/oao) [![Coverage Status](https://coveralls.io/repos/github/guigrpa/oao/badge.svg?branch=master)](https://coveralls.io/github/guigrpa/oao?branch=master) [![npm version](https://img.shields.io/npm/v/oao.svg)](https://www.npmjs.com/package/oao) ![oao all --parallel](https://raw.githubusercontent.com/guigrpa/oao/master/docs/parallel.gif) A Yarn-based, opinionated monorepo management tool. ## Why? :sparkles: - 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 :thought_balloon: 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](https://yarnpkg.com/en/docs/install). If you want to use [**yarn workspaces**](https://yarnpkg.com/blog/2017/08/02/introducing-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): ```sh $ 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 changelog path [CHANGELOG.md] (default: "CHANGELOG.md") --no-changelog skip changelog updates --otp

                                              use 2-factor authentication to publish your package
--access                                            publish public or restricted packages
-h, --help                                                output usage information
```

## Main commands

In recent versions of npm, remember that you can run oao commands conveniently with the `npx` tool:

```sh
$ npx oao bootstrap
$ npx oao add my-subpackage my-new-dependency --dev
$ npx oao publish
```

This uses the local oao package inside your monorepo.

### `oao status`

Provides lots of information on the git repo (current branch, last tag, uncommitted/unpulled changes) and subpackage status (version, private flag, changes since last tag, dependencies).

![oao status](https://raw.githubusercontent.com/guigrpa/oao/master/docs/status.png)

### `oao bootstrap`

Installs all sub-package dependencies using **yarn**. External dependencies are installed normally, whereas those belonging to the monorepo itself (and custom links specified with the `--link` option) are `yarn link`ed. Note that dependencies may end up in different places depending on whether you use [yarn workspaces](https://yarnpkg.com/blog/2017/08/02/introducing-workspaces/) or not (see above).

Development-only dependencies can be skipped by enabling the `--production` option, or setting the `NODE_ENV` environment variable to `production`. Other flags that are passed through to `yarn install` include `--frozen-lockfile`, `--pure-lockfile` and `--no-lockfile`.

### `oao clean`

Removes `node_modules` directories from all sub-packages, as well as from the root package.

### `oao add  `

Adds one or several dependencies to a sub-package. For external dependencies, it passes through [`yarn add`'s flags](https://yarnpkg.com/en/docs/cli/add). Internal dependencies are linked. Examples:

```sh
$ oao add subpackage-1 jest --dev
$ oao add subpackage-2 react subpackage-1 --exact
```

### `oao remove  `

Removes one or several dependencies from a sub-package. Examples:

```sh
$ oao remove subpackage-1 jest
$ oao remove subpackage-2 react subpackage-1
```

### `oao remove-all `

Remove one or deveral dependencies from the monorepo (root and subpackages). It automatically runs `oao bootstrap` after upgrading the `package.json` files as needed. Examples:

```sh
$ oao remove-all leftpad
$ oao remove-all leftpad rightpad centerpad
```

### `oao upgrade  [deps...]`

Upgrade one/several/all dependencies of a sub-package. For external dependencies, it will download the upgraded dependency using yarn. For internal dependencies, it will just update the sub-package's `package.json` file. Examples:

```sh
$ oao upgrade subpackage-1 jest@18.0.1
$ oao upgrade subpackage-2 react subpackage-1@3.1.2
$ oao upgrade subpackage-3
```

### `oao bump `

Upgrade one or several dependencies to either their latest version or to a specific version range. In case of internal dependencies, if no version range is given the current version will be used. It automatically runs `oao bootstrap` after upgrading the `package.json` files as needed. Examples:

```sh
$ oao bump moment
$ oao bump react@^16 react-dom@^16
$ oao bump subpackage-2
```

### `oao outdated`

Runs `yarn outdated` on all sub-packages, as well as the root package.

### `oao prepublish`

Carries out a number of chores that are needed before publishing:

- Checks that all version numbers are valid and <= the master version.
- Copies `/README.md` to the _main_ sub-package (the one having the same name as the monorepo).
- Copies `/README-LINK.md` to all other sub-packages.
- Copies several fields from the root `package.json` to all other `package.json` files: `description`, `keywords`, `author`, `license`, `homepage`, `bugs`, `repository`.

### `oao publish`

Carries out a number of steps:

- Asks the user for confirmation that it has _built_ all sub-packages for publishing (using something like `yarn build`).
- Performs a number of checks:
  - The current branch should be `master` or `main`.
  - No uncommitted changes should remain in the working directory.
  - No unpulled changes should remain.
- Determines which sub-packages need publishing (those which have changed with respect to the last tagged version).
- Asks the user for an incremented master version (major, minor, patch or pre-release major), that will be used for the root package as well as all updated sub-packages.
- Asks the user for final confirmation before publishing.
- Updates versions in `package.json` files, commits the updates, adds a tag and pushes all the changes.
- Publishes updated sub-packages.

There are lots of custom options for `oao publish`. Chances are, you can disable each one of the previous steps by means of one of those options. Check them all with `oao publish --help`.

**Note: There is a problem when running `oao publish` as a script run with `yarn`. As a workaround, either run `oao publish` manually from the command line, or put it in a script and run it with `npm`, not `yarn`.**

### `oao all `

Executes the specified command on all sub-packages (private ones included), with the sub-package's root as _current working directory_. Examples:

```sh
$ oao all ls
$ oao all "ls -al"
$ oao all "yarn run compile"
$ oao all --tree "yarn run compile"
```

By default, `oao all` runs sequentially. Sometimes you must run commands in parallel, for example when you want to compile all sub-packages with a _watch_ option:

```sh
$ oao all "yarn run compileWatch" --parallel
```

**Note: some terminals may have problems with parallel logs (based on [terminal-kit](https://github.com/cronvel/terminal-kit)). If you experience issues, use the `--no-parallel-logs` flag. If you're using the default terminal or Hyper on OS X or Windows, you should be fine.**

Use `--tree` if you want to follow the inverse dependency tree (starting from the tree leaves).

You can also pass extra arguments to the command separating them with a `--`: `oao all ls -- -al` is equivalent to `oao all 'ls -al'`. This can be useful for adding extra commands to scripts in `package.json`.

### `oao run-script

	Stars	Issues	Version	Updated	Created
@microsoft/rush	5,644	835	5.124.6	5 days ago	7 years ago
create-nx-workspace	22,262	748	19.0.4	5 days ago	5 years ago
mondorepo	14	3	0.1.705	8 years ago	8 years ago
oao			2.0.2	3 years ago	7 years ago

@microsoft/rush vs create-nx-workspace vs mondorepo vs oao

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past