@easymetrics/micromanager NPM

What does a Micromanager repo look like?

There's actually very little to it. You have a file system that looks like this:

my-micromanager-repo/
  package.json
  packages/
    package-1/
      package.json
    package-2/
      package.json

What can Micromanager do?

The two primary commands in Micromanager are micromanager bootstrap and micromanager publish.

bootstrap will link dependencies in the repo together. publish will help publish any updated packages.

Getting Started

The instructions below are for Micromanager 2.x. We recommend using it instead of 1.x for a new Micromanager project. Check the wiki if you need to see the 1.x README.

Let's start by installing Micromanager globally with npm.

$ npm install --global micromanager

Next we'll create a new folder:

$ mkdir micromanager-repo
$ cd micromanager-repo

And now let's turn it into a Micromanager repo:

$ micromanager init

This will create a micromanager.json configuration file as well as a packages folder, so your folder should now look like this:

micromanager-repo/
  packages/
  package.json
  micromanager.json

How It Works

Micromanager allows you to manage your project using one of two modes: Fixed or Independent.

Fixed/Locked mode (default)

Fixed mode Micromanager projects operate on a single version line. The version is kept in the micromanager.json file at the root of your project under the version key. When you run micromanager publish, if a module has been updated since the last time a release was made, it will be updated to the new version you're releasing. This means that you only publish a new version of a package when you need to.

This is the mode that Babel is currently using. Use this if you want to automatically tie all package versions together. One issue with this approach is that a major change in any package will result in all packages having a new major version.

Independent mode (`--independent`)

Independent mode Micromanager projects allows maintainers to increment package versions independently of each other. Each time you publish, you will get a prompt for each package that has changed to specify if it's a patch, minor, major or custom change.

Independent mode allows you to more specifically update versions for each package and makes sense for a group of components. Combining this mode with something like semantic-release would make it less painful. (There is work on this already at atlassian/micromanager-semantic-release).

The version key in micromanager.json is ignored in independent mode.

Troubleshooting

If you encounter any issues while using Micromanager please check out our Troubleshooting document where you might find the answer to your problem.

Frequently asked questions

See FAQ.md.

Commands

init

$ micromanager init

Create a new Micromanager repo or upgrade an existing repo to the current version of Micromanager.

Micromanager assumes the repo has already been initialized with git init.

When run, this command will:

Add micromanager as a devDependency in package.json if it doesn't already exist.
Create a micromanager.json config file to store the version number.

Example output on a new git repo:

$ micromanager init
micromanager info version v2.0.0
micromanager info Updating package.json
micromanager info Creating micromanager.json
micromanager success Initialized Micromanager files

--independent, -i

$ micromanager init --independent

This flag tells Micromanager to use independent versioning mode.

--exact

$ micromanager init --exact

By default, micromanager init will use a caret range when adding or updating the local version of micromanager, just like npm install --save-dev micromanager.

To retain the micromanager 1.x behavior of "exact" comparison, pass this flag. It will configure micromanager.json to enforce exact match for all subsequent executions.

{
  "micromanager": "2.0.0",
  "command": {
    "init": {
      "exact": true
    }
  },
  "version": "0.0.0"
}

bootstrap

$ micromanager bootstrap

Bootstrap the packages in the current Micromanager repo. Installs all of their dependencies and links any cross-dependencies.

When run, this command will:

npm install all external dependencies of each package.
Symlink together all Micromanager packages that are dependencies of each other.
npm run prepublish in all bootstrapped packages.
npm run prepare in all bootstrapped packages.

micromanager bootstrap respects the --ignore, --scope and --include-filtered-dependencies flags (see Flags).

Pass extra arguments to npm client by placing them after --:

$ micromanager bootstrap -- --production --no-optional

May also be configured in micromanager.json:

{
  ...
  "npmClient": "yarn",
  "npmClientArgs": ["--production", "--no-optional"]
}

How `bootstrap` works

Let's use babel as an example.

babel-generator and source-map (among others) are dependencies of babel-core.
babel-core's package.json lists both these packages as keys in dependencies, as shown below.

// babel-core package.json
{
  "name": "babel-core",
  ...
  "dependencies": {
    ...
    "babel-generator": "^6.9.0",
    ...
    "source-map": "^0.5.0"
  }
}

Micromanager checks if each dependency is also part of the Micromanager repo.
- In this example, babel-generator can be an internal dependency, while source-map is always an external dependency.
- The version of babel-generator in the package.json of babel-core is satisfied by packages/babel-generator, passing for an internal dependency.
- source-map is npm installed (or yarned) like normal.
packages/babel-core/node_modules/babel-generator symlinks to packages/babel-generator
This allows nested directory imports

Notes:

When a dependency version in a package is not satisfied by a package of the same name in the repo, it will be npm installed (or yarned) like normal.
Dist-tags, like latest, do not satisfy semver ranges.
Circular dependencies result in circular symlinks which may impact your editor/IDE.

Webstorm locks up when circular symlinks are present. To prevent this, add node_modules to the list of ignored files and folders in Preferences | Editor | File Types | Ignored files and folders.

publish

$ micromanager publish

Publish packages in the current Micromanager project. When run, this command does the following:

Creates a new release of the packages that have been updated. Prompts for a new version. Creates a new git commit/tag in the process of publishing to npm.

More specifically, this command will:

Run the equivalent of micromanager updated to determine which packages need to be published.
If necessary, increment the version key in micromanager.json.
Update the package.json of all updated packages to their new versions.
Update all dependencies of the updated packages with the new versions, specified with a caret (^).
Create a new git commit and tag for the new version.
Publish updated packages to npm.

Micromanager won't publish packages which are marked as private ("private": true in the package.json).

--exact

$ micromanager publish --exact

When run with this flag, publish will specify updated dependencies in updated packages exactly (with no punctuation), instead of as semver compatible (with a ^).

For more information, see the package.json dependencies documentation.

--npm-tag tagname

$ micromanager publish --npm-tag=next

When run with this flag, publish will publish to npm with the given npm dist-tag (defaults to latest).

This option can be used to publish a prerelease or beta version.

Note: the latest tag is the one that is used when a user runs npm install my-package. To install a different tag, a user can run npm install my-package@prerelease.

--canary, -c

$ micromanager publish --canary
$ micromanager publish --canary=beta

When run with this flag, publish publishes packages in a more granular way (per commit). Before publishing to npm, it creates the new version tag by taking the current version, bumping it to the next minor version, adding the provided meta suffix (defaults to alpha) and appending the current git sha (ex: 1.0.0 becomes 1.1.0-alpha.81e3b443).

The intended use case for this flag is a per commit level release or nightly release.

--conventional-commits

$ micromanager publish --conventional-commits

When run with this flag, publish will use the Conventional Commits Specification to determine the version bump and generate CHANGELOG

--git-remote remote

$ micromanager publish --git-remote upstream

When run with this flag, publish will push the git changes to the specified remote instead of origin.

--skip-git

$ micromanager publish --skip-git

When run with this flag, publish will publish to npm without running any of the git commands.

Only publish to npm; skip committing, tagging, and pushing git changes (this only affects publish).

--skip-npm

$ micromanager publish --skip-npm

When run with this flag, publish will update all package.json package versions and dependency versions, but it will not actually publish the packages to npm.

This was useful as a workaround for an npm issue which has since been fixed. When publishing with README changes, use --skip-npm and do the final npm publish by hand for each package.

This flag can be combined with --skip-git to just update versions and dependencies, without committing, tagging, pushing or publishing.

Only update versions and dependencies; don't actually publish (this only affects publish).

--force-publish packages

$ micromanager publish --force-publish=package-2,package-4
# force publish all packages
$ micromanager publish --force-publish=*

When run with this flag, publish will force publish the specified packages (comma-separated) or all packages using *.

This will skip the micromanager updated check for changed packages and forces a package that didn't have a git diff change to be updated.

--yes

$ micromanager publish --canary --yes
# skips `Are you sure you want to publish the above changes?`

When run with this flag, publish will skip all confirmation prompts. Useful in Continuous integration (CI) to automatically answer the publish confirmation prompt.

--cd-version

$ micromanager publish --cd-version (major | minor | patch | premajor | preminor | prepatch | prerelease)
# uses the next semantic version(s) value and this skips `Select a new version for...` prompt

When run with this flag, publish will skip the version selection prompt (in independent mode) and use the next specified semantic version. You must still use the --yes flag to avoid all prompts. This is useful when build systems need to publish without command prompts. Works in both normal and independent modes.

--preid

$ micromanager publish --cd-version=prerelease
# uses the next semantic prerelease version, e.g.
# 1.0.0 => 1.0.0-0

$ micromanager publish --cd-version=prepatch --preid=next
# uses the next semantic prerelease version with a specific prerelease identifier, e.g.
# 1.0.0 => 1.0.1-next.0

When run with this flag, micromanager publish --cd-version will increment premajor, preminor, prepatch, or prerelease versions using the specified prerelease identifier.

--repo-version

$ micromanager publish --repo-version 1.0.1
# applies version and skips `Select a new version for...` prompt

When run with this flag, publish will skip the version selection prompt and use the specified version. Useful for bypassing the user input prompt if you already know which version to publish.

--message, -m msg

$ micromanager publish -m "chore(release): publish %s"
# commit message = "chore(release): publish v1.0.0"

$ micromanager publish -m "chore(release): publish" --independent
# commit message = "chore(release): publish
#
# - package-1@3.0.1
# - package-2@1.5.4"

When run with this flag, publish will use the provided message when committing the version updates for publication. Useful for integrating micromanager into projects that expect commit messages to adhere to certain guidelines, such as projects which use commitizen and/or semantic-release.

If the message contains %s, it will be replaced with the new global version version number prefixed with a "v". Note that this only applies when using the default "fixed" versioning mode, as there is no "global" version when using --independent.

--allow-branch glob

Micromanager allows you to specify a glob in your micromanager.json that your current branch needs to match to be publishable. You can use this flag to override this setting. If your micromanager.json contains something like this:

{
    "command": {
        "publish": {
          "allowBranch": "master"
        }
    }
}

and you are not on the branch master micromanager will prevent you from publishing. To force a publish despite this config, pass the --allow-branch flag:

$ micromanager publish --allow-branch my-new-feature

updated

$ micromanager updated

Check which packages have changed since the last release (the last git tag).

Micromanager determines the last git tag created and runs git diff --name-only v6.8.1 to get all files changed since that tag. It then returns an array of packages that have an updated file.

Note that configuration for the publish command also affects the updated command. For example config.publish.ignore

--json

$ micromanager updated --json

When run with this flag, updated will return an array of objects in the following format:

[
  {
    "name": "package",
    "version": "1.0.0",
    "private": false
  }
]

clean

$ micromanager clean

Remove the node_modules directory from all packages.

micromanager clean respects the --ignore, --scope, and --yes flags (see Flags).

diff

$ micromanager diff [package?]

$ micromanager diff
# diff a specific package
$ micromanager diff package-name

Diff all packages or a single package since the last release.

Similar to micromanager updated. This command runs git diff.

ls

$ micromanager ls

List all of the public packages in the current Micromanager repo.

micromanager ls respects the --ignore and --scope flags (see Flags).

--json

$ micromanager ls --json

When run with this flag, ls will return an array of objects in the following format:

[
  {
    "name": "package",
    "version": "1.0.0",
    "private": false
  }
]

run

$ micromanager run <script> -- [..args] # runs npm run my-script in all packages that have it
$ micromanager run test
$ micromanager run build

# watch all packages and transpile on change, streaming prefixed output
$ micromanager run --parallel watch

Run an npm script in each package that contains that script. A double-dash (--) is necessary to pass dashed arguments to the script execution.

micromanager run respects the --concurrency, --scope, --ignore, --stream, and --parallel flags (see Flags).

$ micromanager run --scope my-component test

Note: It is advised to constrain the scope of this command (and micromanager exec, below) when using the --parallel flag, as spawning dozens of subprocesses may be harmful to your shell's equanimity (or maximum file descriptor limit, for example). YMMV

exec

$ micromanager exec -- <command> [..args] # runs the command in all packages
$ micromanager exec -- rm -rf ./node_modules
$ micromanager exec -- protractor conf.js

Run an arbitrary command in each package. A double-dash (--) is necessary to pass dashed flags to the spawned command, but is not necessary when all the arguments are positional.

micromanager exec respects the --concurrency, --scope, --ignore, and --parallel flags (see Flags).

$ micromanager exec --scope my-component -- ls -la

To spawn long-running processes, pass the --parallel flag:

# transpile all modules as they change in every package
$ micromanager exec --parallel -- babel src -d lib -w

You may also get the name of the current package through the environment variable MICROMANAGER_PACKAGE_NAME:

$ micromanager exec -- npm view \$MICROMANAGER_PACKAGE_NAME

You may also run a script located in the root dir, in a complicated dir structure through the environment variable MICROMANAGER_ROOT_PATH:

$ micromanager exec -- node \$MICROMANAGER_ROOT_PATH/scripts/some-script.js

Hint: The commands are spawned in parallel, using the concurrency given (except with --parallel). The output is piped through, so not deterministic. If you want to run the command in one package after another, use it like this:

$ micromanager exec --concurrency 1 -- ls -la

--bail

$ micromanager exec --bail=<boolean> <command>

This flag signifies whether or not the exec command should halt execution upon encountering an error thrown by one of the spawned subprocesses. Its default value is true.

import

$ micromanager import <path-to-external-repository>

Import the package at <path-to-external-repository>, with commit history, into packages/<directory-name>. Original commit authors, dates and messages are preserved. Commits are applied to the current branch.

This is useful for gathering pre-existing standalone packages into a Micromanager repo. Each commit is modified to make changes relative to the package directory. So, for example, the commit that added package.json will instead add packages/<directory-name>/package.json.

link

$ micromanager link

Symlink together all Micromanager packages that are dependencies of each other in the current Micromanager repo.

Misc

Micromanager will log to a micromanager-debug.log file (same as npm-debug.log) when it encounters an error running a command.

Micromanager also has support for scoped packages.

Running micromanager without arguments will show all commands/options.

micromanager.json

{
  "micromanager": "2.0.0",
  "version": "1.1.3",
  "commands": {
    "publish": {
      "ignore": [
        "ignored-file",
        "*.md"
      ]
    },
    "bootstrap": {
      "ignore": "component-*"
    }
  },
  "packages": ["packages/*"]
}

micromanager: the current version of Micromanager being used.
version: the current version of the repository.
commands.publish.ignore: an array of globs that won't be included in micromanager updated/publish. Use this to prevent publishing a new version unnecessarily for changes, such as fixing a README.md typo.
commands.bootstrap.ignore: an array of globs that won't be bootstrapped when running the micromanager bootstrap command.
commands.bootstrap.scope: an array of globs that restricts which packages will be bootstrapped when running the micromanager bootstrap command.
packages: Array of globs to use as package locations.

Common `devDependencies`

Most devDependencies can be pulled up to the root of a Micromanager repo.

This has a few benefits:

All packages use the same version of a given dependency
Can keep dependencies at the root up-to-date with an automated tool such as GreenKeeper
Dependency installation time is reduced
Less storage is needed

Note that devDependencies providing "binary" executables that are used by npm scripts still need to be installed directly in each package where they're used.

For example the nsp dependency is necessary in this case for micromanager run nsp (and npm run nsp within the package's directory) to work correctly:

{
  "scripts": {
    "nsp": "nsp"
  },
  "devDependencies": {
    "nsp": "^2.3.3"
  }
}

Flags

Options to Micromanager can come from configuration (micromanager.json) or on the command line. Additionally options in config can live at the top level or may be applied to specific commands.

Example:

{
  "micromanager": "x.x.x",
  "version": "1.2.0",
  "exampleOption": "foo",
  "command": {
    "init": {
      "exampleOption": "bar",
    }
  },
}

In this case exampleOption will be "foo" for all commands except init, where it will be "bar". In all cases it may be overridden to "baz" on the command-line with --example-option=baz.

--concurrency

How many threads to use when Micromanager parallelizes the tasks (defaults to 4)

$ micromanager publish --concurrency 1

--scope glob

Scopes a command to a subset of packages.

$ micromanager exec --scope my-component -- ls -la

$ micromanager run --scope toolbar-* test

--since ref

When executing a script or command, scope the operation to packages that have been updated since the specified ref. If ref is not specified, it defaults to the latest tag.

List the contents of packages that have changed since the latest tag:

$ micromanager exec --since -- ls -la

Run the tests for all packages that have changed since master:

$ micromanager run test --since master

List all packages that have changed since some-branch:

$ micromanager ls --since some-branch

This can be particularly useful when used in CI, if you can obtain the target branch a PR will be going into, because you can use that as the ref to the --since option. This works well for PRs going into master as well as feature branches.

--flatten

When importing repositories with merge commits with conflicts, the import command will fail trying to apply all commits. The user can use this flag to ask for import of "flat" history, i.e. with each merge commit as a single change the merge introduced.

$ micromanager import ~/Product --flatten

--ignore glob

Excludes a subset of packages when running a command.

$ micromanager bootstrap --ignore component-*

The ignore flag, when used with the bootstrap command, can also be set in micromanager.json under the commands.bootstrap key. The command-line flag will take precedence over this option.

Example

{
  "micromanager": "2.0.0",
  "version": "0.0.0",
  "commands": {
    "bootstrap": {
      "ignore": "component-*"
    }
  }
}

Hint: The glob is matched against the package name defined in package.json, not the directory name the package lives in.

--include-filtered-dependencies

Used in combination with any command that accepts --scope (bootstrap, clean, ls, run, exec). Ensures that all dependencies (and dev dependencies) of any scoped packages (either through --scope or --ignore) are operated on as well.

Note: This will override the --scope and --ignore flags.
i.e. A package matched by the --ignore flag will still be bootstrapped if it is depended on by another package that is being bootstrapped.

This is useful for situations where you want to "set up" a single package that relies on other packages being set up.

$ micromanager bootstrap --scope my-component --include-filtered-dependencies
# my-component and all of its dependencies will be bootstrapped

$ micromanager bootstrap --scope "package-*" --ignore "package-util-*" --include-filtered-dependencies
# all package-util's will be ignored unless they are depended upon by a
# package matched by "package-*"

--loglevel silent|error|warn|success|info|verbose|silly

What level of logs to report. On failure, all logs are written to micromanager-debug.log in the current working directory.

Any logs of a higher level than the setting are shown. The default is "info".

--max-buffer in-bytes

Set a max buffer length for each underlying process call. Useful for example when someone wants to import a repo with a larger amount of commits while running micromanager import. In that case the built-in buffer length might not be sufficient.

--no-sort

By default, all tasks execute on packages in topologically sorted order as to respect the dependency relationships of the packages in question. Cycles are broken on a best-effort basis in a way not guaranteed to be consistent across Micromanager invocations.

Topological sorting can cause concurrency bottlenecks if there are a small number of packages with many dependents or if some packages take a disproportionately long time to execute. The --no-sort option disables sorting, instead executing tasks in an arbitrary order with maximum concurrency.

This option can also help if you run multiple "watch" commands. Since micromanager run will execute commands in topologically sorted order, it can end up waiting for a command before moving on. This will block execution when you run "watch" commands, since they typically never end. An example of a "watch" command is running babel with the --watch CLI flag.

--hoist glob

Install external dependencies matching glob at the repo root so they're available to all packages. Any binaries from these dependencies will be linked into dependent package node_modules/.bin/ directories so they're available for npm scripts. If the option is present but no glob is given the default is ** (hoist everything). This option only affects the bootstrap command.

$ micromanager bootstrap --hoist

For background on --hoist, see the hoist documentation.

Note: If packages depend on different versions of an external dependency, the most commonly used version will be hoisted, and a warning will be emitted.

--nohoist glob

Do not install external dependencies matching glob at the repo root. This can be used to opt out of hoisting for certain dependencies.

$ micromanager bootstrap --hoist --nohoist=babel-*

--npm-client client

Install external dependencies using [client] install. Must be an executable that knows how to install npm dependencies.

$ micromanager bootstrap --npm-client=yarn

May also be configured in micromanager.json:

{
  ...
  "npmClient": "yarn"
}

--use-workspaces

Enables integration with Yarn Workspaces (available since yarn@0.27+). The values in the array are the commands in which Micromanager will delegate operation to Yarn (currently only bootstrapping). If --use-workspaces is true then packages will be overridden by the value from package.json/workspaces. May also be configured in micromanager.json:

{
  ...
  "npmClient": "yarn",
  "useWorkspaces": true
}

The root-level package.json must also include a workspaces array:

{
  "private": true,
  "devDependencies": {
    "micromanager": "^2.2.0"
  },
  "workspaces": [
    "packages/*"
  ]
}

This list is broadly similar to micromanager's packages config (a list of globs matching directories with a package.json), except it does not support recursive globs ("**", a.k.a. "globstars").

--use-git-version

Allow target versions of dependent packages to be written as git hosted urls instead of a plain version number. If enabled, Micromanager will attempt to extract and save the interpackage dependency versions from package.json files using git url-aware parser.

Eg. assuming monorepo with 2 packages where my-package-1 depends on my-package-2, package.json of my-package-1 could be:

// packages/my-package-1/package.json
{
  name: "my-package-1",
  version: "1.0.0",
  bin: "bin.js",
  dependencies: {
    "my-package-2": "github:example-user/my-package-2#v1.0.0"
  },
  devDependencies: {
    "my-dev-dependency": "^1.0.0"
  },
  peerDependencies: {
    "my-peer-dependency": "^1.0.0"
  }
}

For the case above Micromanager will read the version of my-package-2 dependency as 1.0.0.

This allows packages to be distributed via git repos if eg. packages are private and private npm repo is not an option.

Please note that using --use-git-version

is limited to urls with committish part present (ie. github:example-user/my-package-2 is invalid)
requires publish command to be used with --exact

May also be configured in micromanager.json:

{
  ...
  "useGitVersion": true
}

--git-version-prefix

Defines version prefix string (defaults to 'v') ignored when extracting version number from a commitish part of git url. Everything after the prefix will be considered a version.

Eg. given github:example-user/my-package-2#v1.0.0 and gitVersionPrefix: 'v' version will be read as 1.0.0.

Only used if --use-git-version is set to true.

May also be configured in micromanager.json:

{
  ...
  "gitVersionPrefix": "v"
}

--stream

Stream output from child processes immediately, prefixed with the originating package name. This allows output from different packages to be interleaved.

$ micromanager run watch --stream

--parallel

Similar to --stream, but completely disregards concurrency and topological sorting, running a given command or script immediately in all matching packages with prefixed streaming output. This is the preferred flag for long-running processes such as babel src -d lib -w run over many packages.

$ micromanager exec --parallel -- babel src -d lib -w

--registry registry

When run with this flag, forwarded npm commands will use the specified registry for your package(s).

This is useful if you do not want to explicitly set up your registry configuration in all of your package.json files individually when e.g. using private registries.

--temp-tag

When passed, this flag will alter the default publish process by first publishing all changed packages to a temporary dist-tag (micromanager-temp) and then moving the new version(s) to the default dist-tag (latest).

This is not generally necessary, as Micromanager will publish packages in topological order (all dependencies before dependents) by default.

README Badge

Using Micromanager? Add a README badge to show it off:

[![micromanager](https://img.shields.io/badge/maintained%20with-micromanager-cc00ff.svg)](https://micromanagerjs.io/)

What does a Micromanager repo look like?

What can Micromanager do?

Getting Started

How It Works

Fixed/Locked mode (default)

Independent mode (--independent)

Troubleshooting

Frequently asked questions

Commands

init

--independent, -i

--exact

bootstrap

How bootstrap works

publish

--exact

--npm-tag tagname

--canary, -c

--conventional-commits

--git-remote remote

--skip-git

--skip-npm

--force-publish packages

--yes

--cd-version

--preid

--repo-version

--message, -m msg

--allow-branch glob

updated

--json

clean

diff

ls

--json

run

exec

--bail

import

link

Misc

micromanager.json

Common devDependencies

Flags

--concurrency

--scope glob

--since ref

--flatten

--ignore glob

--include-filtered-dependencies

--loglevel silent|error|warn|success|info|verbose|silly

--max-buffer in-bytes

--no-sort

--hoist glob

--nohoist glob

--npm-client client

--use-workspaces

--use-git-version

--git-version-prefix

--stream

--parallel

--registry registry

--temp-tag

README Badge

Independent mode (`--independent`)

How `bootstrap` works

Common `devDependencies`