Monoweave is a tool for managing the versioning and publishing lifecycle of a Yarn-based monorepo.
There are a number of presets to choose from, and many aspects of monoweave can be customized. Out of the box, monoweave supports both an automatic mode that determines versioning from reading commit messages for modified files (via conventional commits), as well as a manual mode that puts the version determination in the hands of the developer (via changeset files).
It is recommended to follow the Getting Started guide in the monoweave documentation. In its simplest form to get started:
yarn add -D @monoweave/cliand then in a monoweave.config.yaml file:
preset: monoweave/preset-recommended # or preset-manual for changeset filesYou can run: yarn monoweave locally to see a dry run of the changes that would be published.
If using GitHub Actions, also check out our release preview reusable action: monoweave/github-action-preview@main.
Monoweave only supports Yarn-modern projects with minimum Node version >=18.19.
| Tool | Package Managers | Monorepo Support | Conventional Commits | Changeset Files | Changelogs | publishConfig overrides | workspace:^ protocol | Version Groups | Pull Request Previews | GitHub Releases | Plugin Support |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Monoweave | yarn | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Lerna | yarn, npm, pnpm | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | 🟨 | ❌ | ✅ | ❌ |
| Lerna Lite | yarn, npm, pnpm | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | 🟨 | ❌ | ✅ | ❌ |
| Yarn Version Plugin | yarn | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ |
| Atlassian Changesets | yarn*, npm, pnpm | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
| Microsoft Beachball | yarn, npm, pnpm | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌* | ❌ |
| Semantic Release | yarn, npm, pnpm | ❌ | ✅ | ❌ | ✅ | ✅ | N/A | N/A | ❌ | ✅ | ✅ |
Legend: ✅ supported, 🟨 partial support, ❌ not supported
If you notice an error or inaccuracy in the above comparison table, please open a GitHub issue. It's not possible to remove bias, however this should still be an accurate representation of how monoweave compares to other tooling.
Feature definitions/notes:
- Package Managers: Monoweave only supports Yarn modern. Changesets partially supports Yarn modern since they don't use Yarn internally to publish so don't natively support Yarn workspace protocols (e.g.
workspace:^). - Monorepo Support: Only semantic release in the above list doesn't support monorepos. All other tools, including monoweave, also support publishing a single non-monorepo package.
- Conventional Commits: Monoweave, Lerna, and Semantic Release all support reading git commit messages according to conventional commits to determine the version strategy to apply. This behaviour can be disabled in monoweave, but is required for semantic release (Lerna does have a way to version from the command line to bypass commit messages).
- Changeset Files: This is called "manual mode" in monoweave, and is a more explicit versioning approach compared to the conventional commits parsing above. Monoweave's changeset files are called "version files" and follow a format very similar to Changesets.
- Changelogs: When using the conventional commits mode with Monoweave, changelogs are generated using conventional changelogs, otherwise there's a default writer that pulls changelogs from manual version files.
- publishConfig overrides: Monoweave uses Yarn publishing internally which will copy some fields from your package.json's publishConfig property. This enables a pattern of having "main" point to source code and "publishConfig.main" point to build artifacts.
- workspace:^ protocol: Yarn supports listing workspace dependencies using
workspace:^andworkspace:*. This instructs Yarn to resolve the dependency to a local version instead of remote. Monoweave removes the workspace protocol during publish and respects the version range specifier (^and*). - Version Groups: Lerna offers a "fixed/locked" mode that ties all versions in a project together, however it's marked as "partial" in the table above since it doesn't offer granularity within a monorepo. Beachball calls this version groups.
- Pull Request Previews: Monoweave has a GitHub Action for pull request previews. It can be adapted for other CI systems if there's demand.
- GitHub Releases: Monoweave implements GitHub releases using the monoweave plugin system. We have some open issues tracking additional functionality for the plugin.
- Plugin Support: Monoweave exposes tappable hooks, this is how the GitHub releases functionality is added. Since Monoweave uses Yarn internally, Yarn plugins can also be used to extend monoweave.
Monoweave respects semantic versioning, however only the @monoweave/cli package is considered entirely "public". The other packages, e.g. @monoweave/changelog are internal and may have unexpected breaking changes if relied upon directly -- we try not to do so, however unlike the CLI, there's less testing of the interface.
In terms of stability and feature completeness, although this GitHub repository is fairly new, monoweave's roots extend from the monodeploy project which has been around for a few years. As can be seen by the above tool comparison table, Monoweave supports all the core features necessary to manage a project. There's always room for improvement though, and contributions are very much welcome.
See the Contributing Guide for setup instructions, tips, and guidelines.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
This project is a fork of Monodeploy (licensed under Apache-2.0) by the original core contributor of Monodeploy.
Note that since this project has been forked from Monodeploy, the original authors of Monodeploy are listed in the contributors section for credit (though the git history wasn't maintained).