Monorepo semantic-release Configuration

semantic-release in a Monorepo

Monorepos require special handling because each package needs independent versioning and publishing. There are several approaches, but the most common uses per-package configuration with the pkgRoot option.

Per-Package Configuration

Place a .releaserc.json in each package directory:

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/npm", {
      "pkgRoot": "."
    }],
    ["@semantic-release/exec", {
      "prepareCmd": "npm run build"
    }],
    "@semantic-release/github"
  ]
}

Root-Level Configuration with Exec

For monorepos managed from the root, use @semantic-release/exec to run package-specific commands:

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/exec", {
      "prepareCmd": "node scripts/update-versions.js ${nextRelease.version}",
      "publishCmd": "node scripts/publish-packages.js"
    }],
    "@semantic-release/github"
  ]
}

Filtering Commits by Path

To ensure each package only triggers releases based on its own changes, use the commit-analyzer with path filtering:

["@semantic-release/commit-analyzer", {
  "preset": "angular",
  "releaseRules": [
    {"type": "feat", "scope": "package-a", "release": "minor"},
    {"type": "fix", "scope": "package-a", "release": "patch"}
  ]
}]

Alternative: semantic-release-monorepo

The semantic-release-monorepo package extends semantic-release to automatically filter commits by package directory, making configuration simpler for large monorepos.