Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
The "Getting Started" process for pubm focuses on initializing the tool within a repository to orchestrate multi-registry publishing across various ecosystems (npm, JSR, crates.io). It automates the detection of project structures—such as monorepos or single-package setups—and streamlines the configuration of versioning strategies, changelog generation, and CI/CD workflows.
At its core, the setup utilizes an interactive CLI wizard (pubm init) or a specialized coding agent skill (publish-setup) to analyze the environment, install necessary dependencies, and generate a pubm.config.ts file when required. This ensures that the project is ready for unified publishing with automatic rollback capabilities.
Installation and Prerequisites
To begin using pubm, the tool must be installed in the development environment. For JavaScript/TypeScript projects, it is recommended to install it as a development dependency. For Rust-only projects or environments without Node.js, a global binary installation is available.
| Method | Command | Description |
|---|---|---|
| npm | npm install -D pubm | Standard for JS/TS projects. Pins version in lockfile. |
| pnpm | pnpm add -D pubm | Recommended for pnpm workspaces. |
| Bun | bun add -d pubm | Recommended for Bun-based projects. |
| Homebrew | brew install pubm | Global binary installation for non-Node environments. |
Sources: CLAUDE.md:36-40, plugins/pubm-plugin/skills/publish-setup/SKILL.md:38-40, README.ko.md:88-95
Core Requirements
- Node.js: Version 24 or later.
- Git: Version 2.11.0 or later.
- Bun: Version 1.3.11 or later (required for repository development).
Sources: CONTRIBUTING.md:43-46, packages/pubm/src/commands/init-workflows.ts:98,113,126,145
The Initialization Workflow
The primary entry point for a new project is the pubm init command. This interactive wizard performs a multi-step analysis and configuration process.
This diagram illustrates the sequential steps taken by the pubm init command to configure a project.
Sources: packages/pubm/src/commands/init.ts:31-150, plugins/pubm-plugin/skills/publish-setup/SKILL.md:14-140
1. Project Analysis
The tool scans for manifest files to determine the ecosystem and registry targets:
- npm: Detected via
package.json. - JSR: Detected via
jsr.json,deno.json, ordeno.jsonc. - crates.io: Detected via
Cargo.toml.
It also identifies workspace structures from pnpm-workspace.yaml, package.json workspaces, or Cargo.toml [workspace] to determine if the project is a monorepo.
Sources: plugins/pubm-plugin/skills/publish-setup/SKILL.md:18-28,42-53, README.ko.md:41-48
2. Configuration Generation
A pubm.config.ts file is generated using defineConfig() for type safety. This file is explicitly required if the user overrides auto-detection or uses plugins.
import { defineConfig } from 'pubm'
export default defineConfig({
packages: [
{ path: 'packages/core', registries: ['npm', 'jsr'] },
],
branch: "main",
versioning: "independent"
})
Sources: packages/pubm/src/commands/init.ts:133-145, plugins/pubm-plugin/skills/publish-setup/SKILL.md:104-124
CI/CD and Workflow Integration
pubm supports automated publishing through GitHub Actions. During setup, users can opt-in to generating workflow files and enabling the "Changesets" workflow.
Automated Workflows
The initialization process can generate two key GitHub Action files:
- release.yml: Handles the actual publishing. For single packages, this is triggered by
v*tags. For monorepos, it triggers on commits starting with "Version Packages". - changeset-check.yml: Validates that Pull Requests include a changeset file, unless the
no-changesetlabel is applied.
Sources: packages/pubm/src/commands/init-workflows.ts:34-45,166-224, plugins/pubm-plugin/skills/publish-setup/SKILL.md:144-160
Workflow Triggers Table
| Project Type | Trigger | Target |
|---|---|---|
| Single Package | push tags | v* |
| Monorepo | push branch | Configured default branch (e.g., main) |
Sources: packages/pubm/src/commands/init-workflows.ts:182-185,212-215
Git Integration
When "Changesets" are enabled, pubm updates the .gitignore file to ensure that the .pubm/ directory is handled correctly:
.pubm/*is ignored to hide internal state.!.pubm/changesets/is explicitly included to ensure changeset files are committed.
Sources: packages/pubm/src/commands/init-workflows.ts:4-32
Summary of Setup Components
Upon completion, the pubm init command provides a summary of the environment.
| Component | Created/Modified | Description |
|---|---|---|
| Changesets | .pubm/changesets/ | Directory for release inputs. |
| Gitignore | .gitignore | Updated with pubm-specific rules. |
| CI Workflows | .github/workflows/ | Action files for release and PR checks. |
| Config File | pubm.config.ts | Central configuration for the release orchestrator. |
| Skills | Coding Agent Assets | Integration for Claude Code, Codex, or Gemini. |
Sources: packages/pubm/src/commands/init.ts:167-183, website/public/INFORMATION.md:27-31
The system is now ready for the core release workflow: adding a changeset via pubm changesets add, inspecting pending versions, and finally publishing using the pubm command.
Sources: website/public/INFORMATION.md:18-25