Getting Started

Monoweave supports projects with the following minimum requirements:

Node v18.19.0+
Yarn Modern (v4.5.0+)
Git 2.13+

Install

@monoweave/cli

yarn add -D @monoweave/cli
yarn monoweave

Edit your project's root
```
package.json
```
and set "workspaces": ["packages/*"] (you can use a different glob to match your monorepo layout).

Create a

monoweave.config.yaml

file and set it to:

preset: monoweave/preset-recommended # or preset-manual for changeset files

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.
In CI, add a step:

yarn monoweave

By default, monoweave will create a release commit, add tags, and push the commit to your git remote. To disable the auto push (for example, if you want to create a pull request instead):

yarn monoweave --no-push
git push --tags

If using GitHub Actions, check out If using GitHub Actions, also check out our release preview reusable action: monoweave/github-action-preview@main to generate release previews on open pull requests.

API

Monoweave supports both a Command Line Interface, as well as a Node API. Explanation of configuration options can be found at Configuration.

CLI

For the CLI, use the

--help

flag for a list of options.

yarn monoweave --help

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 MonoweaveConfigFile interface. CLI flags take precedence over the configuration file.

Example config file (

monoweave.config.js

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

or json/jsonc/json5/yml/yaml:

git:
  commitSha: "HEAD"
  remote: "origin"
  push: true
conventionalChangelogConfig: "conventional-changelog-angular"
access: "infer"
persistVersions: false
changesetIgnorePatterns:
  - "**/*.test.js"

For an experience closer to the Yarn version plugin, or Atlassian's Changesets project, use the manual preset:

module.exports = { preset: 'monoweave/preset-manual' }

and then commit change files generated via:

yarn monoweave version

This will suggest packages to release. You can filter the selection by using one or more globs:

yarn monoweave version "@my-scope/package-a" "@my-scope/package-*"

A non-interactive version is also supported:

yarn monoweave version --no-interactive --strategy=minor --message="Some changelog entry" "@my-scope/package-a"

In this mode, you are choosing not to use conventional changelogs.

Node API

To use the API:

import type { MonoweaveConfiguration }  from '@monoweave/types'
import monoweave from '@monoweave/node'

const config: MonoweaveConfiguration = {
    cwd: process.cwd(),
    dryRun: false,
    git: {
        commitSha: 'HEAD',
        remote: 'origin',
        push: true,
    },
    conventionalChangelogConfig: 'conventional-changelog-angular',
    access: 'infer',
    persistVersions: false,
}
const changeset = await monoweave(config)

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

Changelog

The recommended preset will create changelog entries within each individual package folder. It is equivalent to adding the

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

flag to the CLI. To aggregate changelog entries in a single changelog file, omit the

<packageDir>/

variable.

If adding monoweave to a project with existing changelogs, you'll need to add the a special marker to each changelog file to let monoweave know where to insert the changelog entries. For example:

# My Example Changelog

Some blurb here.

<!-- MONOWEAVE:BELOW -->

## v1.0.0

Some entry.

The marker

<!-- MONOWEAVE:BELOW -->

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

Monoweave uses a simplistic built-in changelog configuration, if a conventional changelog config is not specified, however it is recommended to use a conventional changelog config if possible.