A tool for managing a monorepo via Lerna and Yarn workspaces.
Lerna is a fantastic tool for managing monorepos at a high level, but things go more smoothly when allowing Yarn workspaces to handle the core logic of package resolution and linking at a low level. These two tools are also intended to work together, so Unorepo assumes that you're using both. Because why wouldn't you be? 😄
The purpose of Unorepo is to marry the functionality of Lerna and Yarn workspaces into one easy to use (and easier to remember!) place. Additionally, it adds some extra functionality that isn't present in either tool.
Some of the commands in this utility will merely be aliases to other commands in order to document their use and utility in a single place.
# Install with yarnyarn global add unorepo# Or install with npmnpm i -g unorepo# Display the Unorepo commandsuno --help
A note on language
Lerna and Yarn workspaces have some conflicting language. Given a monorepo of the following structure:
root ├── packages │ ├── foo │ │ └── package.json │ └── bar │ │ └── package.json ├── lerna.json └── package.json
Lerna refers to root as the "lerna workspace" or "lerna repo", and to foo and bar as "packages".
Yarn workspaces refers to root as the "project", and to foo and bar as "workspaces".
The overlapping terminology is very confusing, so in attempt to be as clear as possible, Unorepo will avoid the word "workspace". We will refer to
root as the "project", and
bar as "packages".
Build a package and its dependents every time the package changes.
When a change is detected in a particular package, that package will be built and then each other package in the project that depends on the changed package will also be built. This ensures that all your packages are constantly up to date as you're developing them.
# Watch all file types for all changes, run 'yarn build' on changeuno watch# Run 'yarn local' on changeuno watch --script local# Watch only .ts and .scss files for changeuno watch --ext ts,scss# Run a custom CLI command on changeuno watch --execute 'yarn build && yalc push --no-sig'
||build||The script from
||ALL FILES||The file extensions to watch within the packages. To pass multiple extensions, separate with commas; e.g.
||-||Instead of running a predefined script on change, run an arbitrary CLI command|
||node_modules,dist,build,bld||Files to ignore when watching. This should be a comma separated list of anymatch compatible values. This defaults to a list of common build directories. If specifying a custom value, as applicable make sure to include your own build directory|
||false||Also watch private packages|
uno execute '<command>' [pkg]
Execute an arbitrary CLI
command in one or all packages.
This can be any command that specifies a file (e.g. yarn, npm, echo, etc), followed by arguments. Shell-specific features will not work.
For best results, the
command should be surrounded with quotes.
If the file or an argument contains spaces, they must be escaped with backslashes. This matters especially if command is not a constant but a variable, for example with
process.cwd(). Except for spaces, no escaping/quoting is needed.
uno execute 'echo cat'uno execute --parallel 'pwd'uno execute 'yarn build' my-package
pkg parameter can be any string that is contained in the package name. For example, if you want to run the command in both
@namespace/login-form, you could run:
uno execute '<command>' login
||true||-||The CLI command to run. Must be quoted, and in the form
||false||ALL PACKAGES||The name (or partial name) of the package(s) to run
||false||Run the command in every package simultaneously.|
uno run <script> [pkg]
Run an NPM script (defined in package.json) in one or all packages.
If the second
pkg argument is omitted, the
script will be run in all packages. If
pkg is provided, the
script will only be run in packages that include that string.
This command is similar to
uno execute, but limited to predefined scripts in the package.json of each package.
# Run the 'build' NPM script in all packagesuno run build# Run the 'test' NPM script in packages whose name contain 'login'uno run test login
||true||-||The name of a script defined in the package.json of the package(s)|
||false||ALL PACKAGES||A name (or partial name) of the package(s) to run
||false||Run the script in every package simultaneously|
Show information about each package, including the package's name, its version, and its relative file location within the project. An alias for
lerna list --long.
List each package in the project and the other packages that it depends on. An alias for
yarn workspaces info.
If all your packages are set up correctly, all the dependencies should be listed in the
workspaceDependencies array, and the
mismatchedWorkspaceDependencies arrays should all be empty.
If you have a dependency in
mismatchedWorkspaceDependencies for a particular parent-package, this means that a non-local (probably from NPM or the like) version of that dependency-package will be used when the parent-package is run. So when you then make a local update to the dependency-package, that change will not be reflected in the running parent-package.
The usual cause of this problem is mismatched version numbers. Ensure that the version number listed in the
package.json#version field of the dependency-package matches the version listed in the
package.json#dependencies section of the parent-package.
This linking is what allows your local packages to depend on each other directly in your file system, rather then depending on files copied into
node_modules via a typical (and at times painful) publish and pull method (e.g. using yalc).
Yarn workspaces is really doing all the hard work here of resolving your dependencies and linking them together.
Building the project locally
# Clone the projectgit clone https://github.com/zposten/unorepo.gitcd unorepo# Install dependenciesyarn# Build the projectyarn build# Allow running "uno" in the terminal to run this projectyarn link# Display the options for this CLIuno --help
Note: If you get "permission denied" when running the
yarn postbuild. This can happen if the
yarn buildcommand exits with errors.