FAQ
Can Monodeploy be used without Yarn Modern/Berry?
No. Monodeploy uses Yarn Modern's public API to do most of the heavy lifting in reading and writing to your project.
Can I use monodeploy for non-JavaScript projects?
Yes. The only requirement is that you organize your project using Yarn Berry (i.e. Yarn v3+). You can create a minimal Yarn project by creating a root package.json and then one package.json per package/workspace. In this scenario, you likely want to use the "No Registry" mode.
Although designed for publishing to NPM, you can disable all npm interactions by passing in a --registry-mode manifest flag to the CLI or setting registryMode to manifest in your config file. A registry mode of manifest will set the package.json of each workspace as the source of truth for versions. This means when reading package versions, the package.json is used instead of reading from NPM. Likewise, package publishing to npm is also disabled. If using the "Manifest" registry mode, you should also enable --persistVersions (persistVersions) and commit the modified package.json files to your repository, otherwise there's no proper reference for the package versions.
How can I preview changes before publishing?
You can run:
yarn monodeploy --dry-run --changeset-filename=-
to implicitly disable logs and only output the changeset data. This is useful for previewing changes or determining which packages will be modified from a Pull Request.
Packages I haven't modified are being published with a patch version bump, what's going on?
In addition to the version strategies associated with packages explicitly modified via your commits, what we call the explicit version strategies, Monodeploy will also perform a patch version strategy bump to all dependent packages, what we call implicit version strategies. The idea behind this is that when you run tests and do development in your monorepo, you are always working with the latest packages. Therefore if Package-A depends on Package-B and Package-B has been modified, we also want to release a version of Package-A where Package-A's version range for Package-B has been increased. This Package-A that a downstream project consumes will then be guaranteed to be using the same version of Package-B that is used in the monorepo itself.
As an added benefit, downstream projects using systems like Renovate or Dependabot, will also receive updates for Package-A that will bring in the updated Package-B.
If there is a use case where you believe this behaviour is does not make sense, please open an issue and we'll be glad to discuss.
Note that when using package groups (equivalent of Lerna's fixed mode), the highest version strategy from among each group is chosen. In this case, you may find a dependent package with a minor or even major version bump, assuming such a strategy exists for an intentional bump within said group.
How does Monodeploy handle private packages?
Private packages, i.e. packages containing a private: true field in their manifest, are includes as part of dependency graph traversal and in determining version strategies, but are not published to any registry. Monodeploy filters out private packages from git tag creation as well.
Note that the top level workspace is a special case. It is neither published, nor considered part of the dependency graph. In other words, all dependency paths are terminated at the top level workspace rather than traverse through this workspace.
How can I manually trigger a release (i.e. ignore commits)?
Monodeploy is intended to be entirely automated based on semantic commits. As a result we have not prioritized any manual modes. If manual releases are what you prefer, you may be more interested in the official Yarn Version Plugin. Otherwise, feel free to open a GitHub issue to discuss.
How can I achieve behaviour similar to Lerna's fixed version mode?
Starting in Monodeploy v3, fixed version mode can be achieved by setting the packageGroupManifestField in your monodeploy configuration, or via the CLI argument. This config option should be set to some field in each workspace's manifest file to indicate fixed version grouping. For example, you can add a "group" field set to "components" for some workspaces and "utils" for other workspaces. Monodeploy will then ensure all workspaces with changes (or dependent changes) in the "components" group have the same version bump. To achieve fixed versioning of all workspaces, you need to specify a field that all workspaces have in common. You can also enforce this with the use of the Yarn Constraints plugin.
How does Monodeploy differ from:
Lerna
Unlike Lerna, Monodeploy was designed with Yarn Berry support from the ground up and is optimized for Yarn monorepos. In terms of raw functionality, Monodeploy supports a workflow where versions are not committed back to the git repository. This is useful when it is not feasible to commit back to a repository in CI (for example when using a tool such as Jenkins with many concurrent developers working in a project).
Yarn's Version Plugin
At a high level, Monodeploy is meant for entirely automated workflows, whereas Yarn's version plugin takes a more hands on approach. Monodeploy started out as a Lerna replacement to solve some issues we were having internally with Lerna, and so Lerna's features were the ones we were striving to attain parity with. Read through the Yarn Version Plugin documentation and decide which workflow you prefer, there will be pros and cons to either.