ido-pluto
Semantic Release with NPM Workspaces
Simplify the process of releasing a monorepo with npm workspaces.
Work with:
- Npm workspaces
- Bun workspaces
- Yarn workspaces
- Pnpm workspaces
Only publish packages that changed.
Installation
npm install --save-dev semantic-release-npm-workspaces-monorepoUsage
Add this to your package.json of your workspace root:
{
"workspaces": [
"packages/*"
],
"workspaceRelease": {
"npmRelease": true,
"release": {
// semantic-release configuration
}
},
"scripts": {
"release": "semantic-release-npm-workspaces-monorepo"
}
}The default configuration of this package is:
settings = {
preReleaseVersionTemplate: false, // example: '${version}', override the template in the package.json for pre-release versions
registry: 'https://registry.npmjs.org',
tagFormat: '${name}@${version}',
release: {
extends: 'semantic-release-commit-filter',
ci: true,
branches: [
"main",
"master",
{
name: "beta",
prerelease: true
}
],
plugins: [...]
},
semanticReleaseBin: 'semantic-release',
semanticReleaseBinArgs: [],
// semantic-release pre-configured plugins
changelogCommit: true, // create & update CHANGELOG.md
npmRelease: false, // use NPM_TOKEN to publish packages
extendsReleaseRules: [], // extend defaults release rules
extendsNoteGeneratorTypes: [], // extend defaults note generator types
extendsDefaultPlugins: [], // add custom plugins additonally to the pre-configured plugins
}How it works
- It will update all the workspace (local dependencies) to the latest version from the registry before running semantic release, respecting configured release channels. When working in a prerelease branch (e.g., beta), it will fetch the latest prerelease version from that channel if available.
- It will do it by the dependency graph, meaning that it will update the packages in the correct order.
- Use
semantic-release-commit-filterto filter the commits to only publish packages that changed.
Pre-configured plugins
If you do not specify the plugins property in the release object, it will use the following plugins:
- @semantic-release/commit-analyzer
- @semantic-release/release-notes-generator
- @semantic-release/changelog (if
changelogCommitis set true) - @semantic-release/npm (if
npmReleaseis set true) - @semantic-release/github (if
changelogCommitis set true) - @semantic-release/git (if
changelogCommitis set true)
The plugins configure with recommended settings.
Checkout settings.ts for more information.
Per Package Configuration
If you need the flexibility to configure some packages separately, you can use the perPackageConfig object within the workspaceRelease object.
{
"workspaces": [
"packages/*"
],
"workspaceRelease": {
"npmRelease": true,
"perPackageConfig": {
"packages/internal/**": {
// override specific configuration
"npmRelease": false
}
}
},
"scripts": {
"release": "semantic-release-npm-workspaces-monorepo"
}
}Examples
Some examples of how to use this package:
How to "Breaking Changes"?
The release of breaking changes can be confusing sometimes.
You need to write a commit message with BREAKING CHANGE in the footer of the commit to trigger a major release.
(You cannot use BREAKING CHANGE as the type)
git commit -m "feat: add new feature
BREAKING CHANGE: this is a breaking change"To ease the process, you can use the breaking type in the commit message to trigger a major release in one line.
git commit -m "breaking: this is a breaking change"