Monorepo & Workspace Support
Relevant source files
The following files were used as context for generating this wiki page:
Pubm provides comprehensive support for monorepo architectures, enabling the management and publishing of multiple packages across different ecosystems (JavaScript/TypeScript and Rust) within a single repository. It supports major workspace orchestrators including Turborepo, Bun workspaces, pnpm-workspaces, and Cargo workspaces.
The system automates the complexities of monorepo management, such as resolving internal dependency protocols (e.g., workspace:), coordinating version bumps across linked packages, and managing CI/CD pipelines that trigger specifically when package versions are updated.
Sources: CLAUDE.md:12-25, plugins/pubm-plugin/skills/publish-setup/SKILL.md:21-45
Workspace Detection and Management
Pubm identifies the project structure by scanning for manifest files and workspace configurations. This detection determines whether the project is treated as a single-package repository or a monorepo.
Supported Workspace Types
Pubm detects workspaces based on the presence of specific configuration files and lockfiles:
| Ecosystem | Configuration File | Lockfile |
|---|---|---|
| Bun | package.json (workspaces) | bun.lock |
| pnpm | pnpm-workspace.yaml | pnpm-lock.yaml |
| Yarn | package.json (workspaces) | yarn.lock |
| npm | package.json (workspaces) | package-lock.json |
| Cargo | Cargo.toml ([workspace]) | Cargo.lock |
Sources: packages/pubm/src/commands/init-workflows.ts:64-75, plugins/pubm-plugin/skills/publish-setup/SKILL.md:21-45
Workspace Protocol Resolution
In monorepos, packages often reference each other using the workspace: protocol. Pubm resolves these temporary placeholders to actual semantic versions during the publishing phase to ensure registry compatibility.
- Dynamic Resolution: Protocols like
workspace:*,workspace:^, andworkspace:~are replaced with the target package's current version or a corresponding range. - Prefix Stripping: Static workspace references (e.g.,
workspace:1.2.0) have the prefix removed to become standard SemVer strings. - Restoration: To maintain the integrity of the source code, Pubm creates backups of manifests and restores the original
workspace:protocols after the publishing task completes.
Sources: packages/pubm/tests/e2e/workspace-protocol.test.ts:31-105, packages/core/tests/unit/monorepo/resolve-workspace.test.ts:40-75
Versioning Strategies
Pubm supports three primary versioning modes for monorepos, allowing developers to choose between unified or granular control.
Fixed Versioning
All packages in the monorepo share the same version number. When a release is triggered, every package in the "fixed" group is bumped to the new version simultaneously, regardless of whether individual packages had changes.
Independent Versioning
Each package maintains its own version history. Bumps are determined per-package based on changesets or conventional commits. This is the standard for large monorepos where packages are loosely coupled.
Linked Groups
A hybrid approach where specific subsets of packages are "linked." When one package in a linked group is bumped, others in the same group are also updated to maintain compatibility, even if they don't share the exact same version number (e.g., synchronized major versions).
The diagram shows the logic flow during the versioning command execution, specifically how different strategies branch out.
Sources: packages/core/src/tasks/phases/version.ts:47-230, packages/pubm/src/commands/version-cmd.ts:40-100
Monorepo Release Workflow
The release process in a monorepo differs from single packages primarily in how CI/CD is triggered. While single packages often use tag-based triggers (e.g., v*), monorepos utilize Commit-based triggers.
Trigger Logic
Release workflows for monorepos are configured to trigger on a push to the default branch (usually main) only if the head commit message starts with "Version Packages". This allows Pubm to:
- Consume changesets in a PR.
- Create a "Version Packages" commit containing all bumped manifest versions.
- Trigger the final publish only after the versioning commit is merged to the main branch.
Sources: packages/pubm/src/commands/init-workflows.ts:145-165, plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:144-165
Dependency Ordering
During publishing, Pubm calculates the dependency graph of the workspace. Packages are published in topological order to ensure that if Package B depends on Package A, Package A is already available in the registry before Package B is uploaded.
Sources: CLAUDE.md:12-18, plugins/pubm-plugin/skills/publish-setup/SKILL.md:40-50
CI/CD Workflow Generation
Pubm's init command generates specialized GitHub Action workflows tailored for monorepo structures.
The sequence diagram illustrates the automated flow from a merged version commit to the final multi-registry publication in a monorepo context.
Sources: packages/pubm/src/commands/init-workflows.ts:145-175, plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:144-170
Gitignore Management
To support the changeset workflow in a monorepo, Pubm manages .gitignore entries. It ensures that while general .pubm/ files are ignored, the changesets directory is explicitly tracked:
.pubm/*
!.pubm/changesets/
Sources: packages/pubm/src/commands/init-workflows.ts:5-30
Conclusion
Monorepo support in Pubm is designed to be "zero-config" where possible, automatically detecting workspace boundaries and handling complex dependency resolution. By supporting both fixed and independent versioning and providing specialized CI triggers, it provides a robust pipeline for multi-package projects across varied ecosystems.
Sources: plugins/pubm-plugin/skills/publish-setup/SKILL.md:10-30, packages/core/src/tasks/phases/version.ts:220-230