Highly opinionated set of utilities to orchestrate and administrate mono repositories.
The mono-repos
project assumes the following:
- Packages live in the
packages
folder in the root of the repository. - Each package has their own individual version number.
- A publish should be easy trackable in Github, using
tags
.
This library should be installed as devDependency
in the root of your
mono repository.
npm install --save-dev mono-repos
But as it ships with a CLI tool it can also be installed globally.
npm install --global mono-repos
const Mono = require('mono-repos');
The mono
constructor accepts 2 arguments:
root
This is the absolute path to the root of the mono repository.options
Default configuration for the projects.
const mono = new Mono(process.cwd(), { /* options here */ });
In addition to the options
argument that you can pass into the Mono
constructor we also support reading of global config files/values:
package.json#mono
Add a newmono
object to yourpackage.json
where you specify the config values..monorc
Creating a dedicated.monorc
file in JSON format, and specify the configuration values there. If a.monorc
file is found, we will ignore the values that are specified inpackage.json#mono
.
The mono
instance has the following methods and properties available:
- mono.root
- mono.git
- mono#repo
- mono#resolve
- mono#verify
- mono#each
- mono#packages
- mono#publish
- mono#install
- mono#link
- mono#test
This is the absolute path to where the mono repository is located
console.log(mono.root);
A pre-configured git-shizzle
cli wrapper for interacting with the git
repository.
console.log(mono.git.changes()) // lists all unstaged changes
Returns a new Repo instance for a given package name. The name should
be a name of a folder which is in the /packages
folder.
const repo = mono.repo('package-name');
See Repo for the available methods on the repo instance.
Helper function to resolve the path package. It basically joins the name given
name with mono.root
and the known packages
folder.
const loc = mono.resolve('package-name');
console.log(loc); // /current/working-directory/packages/package-name
Verifies that the repo is in a good state to publish. Returns a boolean as success indication.
mono.verify();
Iterates over all packages in the /packages
folder. It accepts a function or
a string as first argument. When it's a function, it assumes it's an iterator
function. This function will receive a Repo instance as first argument.
When a string is supplied it will assume it's a method name that needs be called
on the Repo instance. Any other argument supplied to the mono#each
method will then be used as argument for the method.
mono.each('publish'); // iterates over all packages, calls repo#publish on all.
//
// Same as above, but then passes the object in to the repo#publish method
//
mono.each('publish', { release: 'major' });
//
// Which are all short hands for writing:
//
mono.each(function each(repo) {
return repo.publish();
});
It's worth noting that the mono#each
method will stop iterating over the
packages when you return a false
in the callback. This is useful for cases
when you do not want to continue publishing when an error occurs etc.
Returns an array with the names of the npm packages that are hosted in the
/packages
folder.
mono.packages(); // ["package-name", "another", ..]
Install the dependencies of all the package.
mono.install()
This is a shorthand method for;
mono.each('install');
Publishes all the packages.
mono.publish({
release: 'major',
message: 'optional commit message, see Repo#publish for more information'
})
This is a shorthand method for:
mono.each('publish');
Setups the symlinks of in the node_module
folders of all packages.
mono.link();
This is a shorthand method for:
mono.each('link');
Run all the tests.
mono.test();
This is a shorthand method for:
mono.each('test');
The Repo
class represents a single package from the packages
folder. The
package has the following methods and properties are available:
The name of the package. This corresponds with the folder name in /packages
const repo = mono.repo('package-name');
console.log(repo.name); // package-name
The absolute path to the package folder
const repo = mono.repo('package-name');
console.log(repo.root); // /root/folder/packages/package-name
Pre-configured npm-shizzle
cli wrapper that only operates in the package
folder.
const repo = mono.repo('package-name');
repo.npm.install('--save', 'diagnostics');
The snippet above will save a new dependency in the package.json
of the file.
Merges the provided options with the options that were originally provided to
the mono
instance. This allows you to supply defaults options to the mono
instance. This method used by all repo methods that accept options.
const mono = new Mono(process.cwd(), {
foo: 'bar',
bar: 'baz'
});
const repo = mono.repo('hello world');
const options = repo.configure({ bar: 'hi', release: 'major' });
// options is now: { foo: 'bar', bar: 'hi', release: 'major' }
Read out the package.json
of the package.
const repo = mono.repo('package-name');
const data = repo.read();
console.log(data.version, data.dependencies);
Publish a new version of the package. The process will start the following operations in the package:
- Bump the version number of the
package.json
file. - Create a new
[dist] ${name}@${version}
commit. - Create a new git tag
${name}@${version}
. - Push tags, and commit to the current branch.
- Run
npm publish
to publish the version tonpm
.
const repo = mono.repo('name of project');
repo.publish({ release: 'patch' });
The method accepts an optional object with the following keys:
release
Type of version bump we want to do, can either bepatch
,minor
ormajor
.version
Instead of an automated version bump, bump the project to the specified version number.message
Additional commit message.
If no options are provided, it will use the options object that was originally
provided to the mono
instance.
Install all the dependencies of the given project.
const repo = mono.repo('name of project');
repo.install();
Run the test of a given project.
const repo = mono.repo('name of project');
repo.test();
Symlink all projects from the packages
folder if we have a dependency
or
devDependency
on them.
const repo = mono.repo('name of project');
repo.link();
The project comes with a build-in CLI called mono
. This provides some basic
repo management utilities such as (mass and targeted) publish, test, link and
installation.
When supplying mono
without arguments you will be presented with the help
menu:
mono:help:
mono:help: mono(-repos): Mono repo management made easy
mono:help:
mono:help: usage: mono [flags]
mono:help:
mono:help: --publish [name] Publish all packages, when a name is given only release
mono:help: that given package instead of all packages.
mono:help: --release [type] Type of release, either `patch`, `minor` or `major`.
mono:help: --version [semver] Instead of an automated bump, release the specified version.
mono:help: --message="message" Optional message for the publish.
mono:help: --test [name] Run the test suite, all, or for the given name.
mono:help: --link [name] npm link packages, all, or for the given name.
mono:help: --install [name] npm install dependencies, all, or for the given name.
mono:help:
mono:help: examples:
mono:help:
mono:help: mono --publish foo --release patch
mono:help: mono --install && mono --link
mono:help:
The project is released under the MIT license