Configuration Guide
Relevant source files
The following files were used as context for generating this wiki page:
The configuration system in pubm is designed to be "auto-detection first," meaning a dedicated configuration file is only necessary when overriding default behaviors or extending the pipeline with plugins. It supports multiple file formats, including TypeScript (.ts, .mts, .cts) and JavaScript (.js, .mjs, .cjs), allowing for type-safe configuration via the defineConfig utility.
The guide covers how the system loads configuration, the available options for packages and global release settings, and how to integrate external plugins or custom versioning strategies.
Configuration Discovery and Loading
pubm searches for configuration files in the project root using a specific priority order. The system employs a sophisticated loading mechanism that can handle native ESM imports, bundled builds for TypeScript, and execution within a Node.js VM context to ensure compatibility across different environments.
Search Order
The loader checks for the following files in order:
pubm.config.tspubm.config.mtspubm.config.ctspubm.config.jspubm.config.mjspubm.config.cjs
Sources: packages/core/src/config/loader.ts:13-20, plugins/pubm-plugin/skills/publish-setup/references/config-examples.md:14-22
Loading Logic
If native import fails (e.g., due to TypeScript syntax), pubm attempts to bundle the config using Bun.build or a child process fallback. It handles import.meta rewrites and optional dependency shimming to prevent evaluation errors when certain plugins are missing.
Core Configuration Options
The configuration is structured into global options and package-specific settings. Global options control the release flow, git behavior, and changelog generation.
Global Options
| Option | Type | Default | Description |
|---|---|---|---|
versioning | 'independent' | 'fixed' | 'independent' | Determines if all packages share a version or bump separately. |
branch | string | 'main' | The target branch allowed for releases. |
changelog | boolean | string | true | Enables CHANGELOG.md generation or points to a template. |
changelogFormat | 'default' | 'github' | 'default' | Style of the generated changelog. |
releaseDraft | boolean | true | Whether to create the GitHub release as a draft. |
versionSources | 'all' | 'changesets' | 'commits' | 'all' | Sources used to determine version bumps. |
Sources: plugins/pubm-plugin/skills/publish-setup/references/config-examples.md:144-192, packages/pubm/src/commands/version-cmd.ts:40-50
Package Configuration
The packages array allows fine-grained control over individual directories in a monorepo.
// Example: Explicit Package Config
export default defineConfig({
packages: [
{
path: 'packages/core',
registries: ['npm', 'jsr'],
buildCommand: 'npm run build:core'
},
{
path: 'crates/logic',
registries: ['crates']
}
]
})
Sources: plugins/pubm-plugin/skills/publish-setup/references/config-examples.md:38-45, plugins/pubm-plugin/skills/publish-setup/references/config-examples.md:118-125
Versioning and Changesets
pubm supports multiple versioning strategies, primarily driven by "Recommendations" from various sources.
Version Sources
The system analyzes two primary sources to suggest the next version:
- Changesets: Markdown files in
.pubm/changesets/describing specific changes. - Conventional Commits: Git history analysis (fallback or primary).
Monorepo Groups
- Fixed Groups: Packages that must always share the same version number.
- Linked Groups: Packages that bump together but may have different version numbers.
Sources: packages/core/src/migrate/config-writer.ts:15-16, packages/pubm/src/commands/version-cmd.ts:88-105
Plugin System
Plugins allow users to hook into the lifecycle of the release process. They are registered in the plugins array and usually follow a factory function pattern.
Plugin Lifecycle Hooks
Available hooks for configuration include:
beforeVersion/afterVersionbeforePublish/afterPublishafterRelease(receives GitHub Release metadata)onError(for custom rollback logic)
Sources: plugins/pubm-plugin/skills/publish-setup/SKILL.md:117-133, packages/core/src/i18n/locales/en.json:148-160
Official Plugin Examples
- externalVersionSync: Syncs versions to non-manifest files (e.g., READMEs).
- brewTap / brewCore: Updates Homebrew formulas upon release.
Sources: plugins/pubm-plugin/skills/publish-setup/references/config-examples.md:82-95, plugins/pubm-plugin/skills/publish-setup/references/config-examples.md:104-114
Validation and Rollback
Configuring validate allows project maintainers to ensure environment health before a publish begins.
| Validation Field | Default | Description |
|---|---|---|
cleanInstall | true | Runs an install check to ensure no lockfile drift. |
entryPoints | true | Validates that package entry points exist in the file system. |
extraneousFiles | true | Checks for files that shouldn't be published. |
Sources: plugins/pubm-plugin/skills/publish-setup/references/config-examples.md:195-201, packages/core/src/i18n/locales/en.json:44-55
Rollback Strategy
The rollbackStrategy can be set to 'individual' (only roll back the failed package) or 'all' (revert the entire release across all packages).
Sources: plugins/pubm-plugin/skills/publish-setup/references/config-examples.md:164-164
Summary
The pubm configuration system balances ease of use with deep extensibility. By leveraging auto-detection for standard projects and a robust TypeScript-based loader for complex monorepos, it provides a stable environment for multi-registry publishing. Developers can start with zero config and incrementally add pubm.config.ts as requirements for custom plugins, versioning groups, or CI integrations arise.