Getting Started

Monodeploy supports projects with the following minimum requirements:

Node v18.12.0
Yarn Modern (v4.0.0)
Git 2.13

Install monodeploy:

yarn add -D monodeploy
yarn monodeploy --dry-run

Edit your project's root package.json:

Set "workspaces": ["packages/*"] (you can use a different glob to match your monorepo layout)
Create a monodeploy.config.js file and set it to:

module.exports = { preset: 'monodeploy/preset-recommended' }

You'll be extending this file as you make changes to your project's publish configuration.

If your packages require a compilation step (e.g. TypeScript, Babel), do this in a 'prepack' lifecycle hook per workspace. For more information about when prepack is called, see Lifecycle Scripts.

For help with the CLI options:

yarn monodeploy --help

or see the Configuration page for more details.

API

Monodeploy supports both a Command Line Interface, as well as a Node API.

CLI

For the CLI, use the --help flag for a list of options.

yarn monodeploy --help

If you are okay with the defaults, you can go ahead and add a call to monodeploy to your CI's publish stage:

yarn monodeploy --push

If you omit --push, you can manually push the tags on success:

yarn monodeploy && git push --tags

Or to give things a try first, run monodeploy in dry run mode with verbose logging. Dry run mode won't modify the remote registry, or git.

yarn monodeploy --dry-run --log-level 0

The CLI provides a few sensible defaults, however if using the Node API, you will have to provide all relevant information.

You can also pass a --config-file flag to load options from a configuration file. The file should export an object matching the MonodeployConfiguration interface (with all properties as optional). CLI flags take precedence over the configuration file.

Example config file:

module.exports = {
    dryRun: false,
    git: {
        commitSha: 'HEAD',
        remote: 'origin',
        push: true,
    },
    conventionalChangelogConfig: '@tophat/conventional-changelog-config',
    access: 'infer',
    persistVersions: false,
    changesetIgnorePatterns: ['**/*.test.js'],
}

Node API

To use the API:

import type { MonodeployConfiguration }  from '@monodeploy/types'
import monodeploy from '@monodeploy/node'

const config: MonodeployConfiguration = {
    cwd: process.cwd(),
    dryRun: false,
    git: {
        commitSha: 'HEAD',
        remote: 'origin',
        push: true,
    },
    conventionalChangelogConfig: '@tophat/conventional-changelog-config',
    access: 'infer',
    persistVersions: false,
}
const changeset = await monodeploy(config)

Note that configuration presets are not supported when using the Node API.

Changelog

If you choose to use the --changelog-filename CHANGELOG.md flag or related API config property, in your CHANGELOG.md file you'll need to insert a marker to let monodeploy know where to insert the changelog entries. For example:

# My Example Changelog

Some blurb here.

<!-- MONODEPLOY:BELOW -->

## v1.0.0

Some entry.

The marker  must match exactly. It is whitespace and case-sensitive.

You can use the template variable <packageDir> to create individual changelogs per package, like so:

--changelog-filename "<packageDir>/CHANGELOG.md"