Konfiguration

pubm ist bewusst CLI-first, aber echte Projekte wachsen schnell über eine reine Flag-Konfiguration hinaus. In pubm.config.* legst du Repository-weite Publish-Ziele, Paketlayout, Plugins und Changeset-bezogene Versionsregeln ab.

Fuehre pubm init aus, um diese Konfigurationsdatei interaktiv zu erzeugen. Der Wizard erstellt eine Config-Datei nur dann, wenn deine Auswahl von den unten gezeigten Standardwerten abweicht.

Unterstützte Config-Dateien

pubm unterstützt diese Dateinamen:

1. pubm.config.ts
2. pubm.config.mts
3. pubm.config.cts
4. pubm.config.js
5. pubm.config.mjs
6. pubm.config.cjs

TypeScript-Config-Dateien werden direkt unterstützt. Der Loader bundlelt die Datei vor der Auswertung, daher brauchst du keinen separaten Runtime-Transpilierschritt.

Standardkonfiguration

Das sind die Standardwerte, die von der Konfigurationsschicht aufgeloest werden:

export default defineConfig({
  versioning: "independent",
  branch: "main",
  changelog: true,
  changelogFormat: "default",
  commit: false,
  access: "public",
  fixed: [],
  linked: [],
  updateInternalDependencies: "patch",
  ignore: [],
  tag: "latest",
  contents: ".",
  saveToken: true,
  releaseDraft: true,
  releaseNotes: true,
  rollback: {
    strategy: "individual",
    dangerouslyAllowUnpublish: false,
  },
  packages: [{ path: "." }],
  validate: {
    cleanInstall: true,
    entryPoints: true,
    extraneousFiles: true,
  },
  snapshotTemplate: "{tag}-{timestamp}",
  locale: "en",
});

Wie Registries abgeleitet werden

pubm untersucht Manifest-Dateien in jedem Paketverzeichnis und ordnet sie Registries zu:

Manifest	Abgeleitete Registry
package.json	npm
jsr.json	jsr
deno.json / deno.jsonc	jsr
Cargo.toml	crates

Für npm gelten zwei zusätzliche Regeln:

• publishConfig.registry in package.json ersetzt npm durch diese benutzerdefinierte URL
• .npmrc-Registry ersetzt npm, wenn publishConfig nicht vorhanden ist

Optionen auf oberster Ebene

versioning

• Typ: "independent" | "fixed"
• Standard: "independent"

Steuert, wie Versionen in Repositories mit mehreren Paketen vergeben werden.

branch

• Typ: string
• Standard: "main"

Branch, der bei abgesicherten Release-Laeufen mit HEAD uebereinstimmen muss.

packages

• Typ: PackageConfig[]
• Standard: [{ path: "." }]

Deklariert explizit publishbare Pakete. Registries werden aus Manifest-Dateien abgeleitet, sofern sie nicht pro Paket ueberschrieben werden.

plugins

• Typ: PubmPlugin[]
• Standard: []

Registriert Plugins, die Hooks, Befehle, Registries oder Ecosystems hinzufuegen koennen.

fixed

• Typ: string[][]
• Standard: []

Gruppen von Paketen, die immer auf exakt derselben Version landen muessen.

linked

• Typ: string[][]
• Standard: []

Gruppen von Paketen, die denselben hoechsten Versionssprung teilen sollen.

ignore

• Typ: string[]
• Standard: []

Paketnamen oder Pfade, die von der Workspace-Erkennung ausgeschlossen werden.

tag

• Typ: string
• Standard: "latest"

Standard-Dist-Tag für Publish-Laeufe.

contents

• Typ: string
• Standard: "."

Verzeichnis, in das vor dem Start der Release-Pipeline gewechselt wird.

saveToken

• Typ: boolean
• Standard: true

Ob unterstützte Registry-Tokens für spätere lokale Laeufe gespeichert werden sollen.

releaseDraft

• Typ: boolean
• Standard: true

Ob der Publish-Flow einen GitHub Release erstellen soll. Wenn deaktiviert, wird der Release-Schritt komplett uebersprungen.

excludeRelease

• Typ: string[]
• Standard: []

Glob-Muster für Pakete, die versioniert und veröffentlicht, aber von der Git-Tag-Erstellung und GitHub-Release-Entwuerfen ausgeschlossen werden sollen. Gilt nur bei versioning: "independent".

Verwende dies für interne Build-Artefakte, z.B. plattformspezifische Binaerdateien, die in eine Registry veröffentlicht werden, aber nicht als eigenstaendige Releases erscheinen sollen.

export default defineConfig({
  versioning: "independent",
  excludeRelease: ["packages/cli/platforms/*"],
  packages: [
    { path: "packages/core" },
    { path: "packages/cli" },
    { path: "packages/cli/platforms/*" },
  ],
});

validate

• Typ: ValidateConfig

Diese Felder sind Teil des oeffentlichen Schemas, aber noch nicht in jedem Publish-Pfad als aktive Schalter angeschlossen. Betrachte sie als typisierte Config-Oberflaeche, nicht als garantiert aktive Runtime-Schalter.

snapshotTemplate

• Typ: string
• Standard: "{tag}-{timestamp}"

Vorlage, die verwendet wird, wenn pubm --snapshot eine temporaere Versionszeichenkette erzeugt.

Verfügbare Platzhalter:

• {base}: aktuelle Paketversion aus dem Manifest
• {tag}: Snapshot-Tag, standardmaessig snapshot
• {timestamp}: UTC-Zeitstempel im Format YYYYMMDDTHHmmss
• {commit}: aktueller Git-Commit-SHA

In Monorepo-Projekten mit fixed-Versionierung wird das Template einmal angewendet, wobei die Version des ersten Pakets als {base} verwendet wird. Mit independent-Versionierung generiert jedes Paket seine eigene Snapshot-Version mit dem eigenen {base}.

createPr

• Typ: boolean
• Standard: false

Erstellt einen Pull Request für den Version-Bump-Commit anstatt direkt in den Basis-Branch zu pushen. Wenn aktiviert, erstellt pubm einen pubm/version-packages-*-Branch, pusht ihn und öffnet einen PR. Der Release-Workflow wird normal ausgelöst, wenn der PR gemergt wird.

pubm fällt auch automatisch in den PR-Modus zurück, wenn ein direkter Push in einen geschützten Branch fehlschlägt.

locale

• Typ: "en" | "ko" | "zh-cn" | "fr" | "de" | "es"
• Standard: "en"

Sprache der CLI-Ausgabe. Kann auch über das Flag --locale oder die Umgebungsvariable PUBM_LOCALE gesetzt werden. Auflösungsreihenfolge: Flag --locale → Umgebungsvariable PUBM_LOCALE → Config → Systemsprache → "en".

rollback

Steuert das Rollback-Verhalten bei einem fehlgeschlagenen Publish.

Schlüssel	Typ	Standard	Beschreibung
strategy	"individual" | "all"	"individual"	Rollback-Granularität. Ersetzt das veraltete Top-Level-Feld rollbackStrategy.
dangerouslyAllowUnpublish	boolean	false	Erlaubt Registry-Unpublish/Yank während des Rollbacks in Nicht-TTY-Umgebungen (CI). Auch nach einem Unpublish reserviert npm die Versionsnummer dauerhaft: sie kann nicht wiederverwendet werden.

export default defineConfig({
  rollback: {
    strategy: "individual",
    dangerouslyAllowUnpublish: true, // für CI aktivieren
  },
});

Das veraltete Top-Level-Feld rollbackStrategy funktioniert weiterhin und wird auf rollback.strategy abgebildet. Wenn beide gesetzt sind, hat rollback.strategy Vorrang.

Wie Config und CLI-Flags zusammenspielen

Das aktuelle Laufzeitverhalten ist:

• die Config liefert Repository-Standardwerte für packages und plugins
• versionsbezogene Config wie versioning, fixed und linked wird von Changeset-Flows verwendet
• CLI-Flags steuern weiterhin das Verhalten pro Lauf
• Registries werden aus Manifests abgeleitet; packages[].registries überschreibt diese Ableitung

Für eine einmalige Veröffentlichung in eine bestimmte Registry:

pubm --registry npm --tag beta

Multi-Paket-Konfiguration

Für Workspaces oder gemischte Repositories mit mehreren Sprachen solltest du Pakete explizit deklarieren. Registries werden aus den Manifest-Dateien jedes Pakets abgeleitet:

import { defineConfig } from "@pubm/core";

export default defineConfig({
  versioning: "independent",
  packages: [
    {
      path: "packages/core",
    },
    {
      path: "packages/cli",
      registries: ["npm"],
    },
    {
      path: "crates/pubm-rs",
    },
  ],
});

Verwende explizite Paket-Eintraege, wenn:

• du willst, dass pubm nur eine Teilmenge der gefundenen Workspace-Pakete veröffentlicht
• JavaScript- und Rust-Pakete im selben Repository leben
• du abgeleitete Registries überschreiben oder private Registries hinzufuegen musst

PackageConfig

Paketbezogene Eintraege sehen so aus:

interface PackageConfig {
  path: string;
  registries?: Array<"npm" | "jsr" | "crates" | PrivateRegistryConfig>;
  ecosystem?: "js" | "rust";
  buildCommand?: string;
  testCommand?: string;
}

interface PrivateRegistryConfig {
  url: string;
  token: { envVar: string };
}

Verwende registries nur, wenn die Ableitung nicht ausreicht oder wenn du neben eingebauten Registries noch private Registries hinzufuegen willst:

packages: [
  {
    path: "packages/a",
    registries: [
      "npm",
      { url: "https://npm.internal.com", token: { envVar: "INTERNAL_NPM_TOKEN" } },
    ],
  },
];

Versionierungsstrategien

Unabhängige Versionierung

Jedes Paket bekommt seine eigene Version und seinen eigenen Tag.

export default defineConfig({
  versioning: "independent",
});

Feste Versionierung

Alle betroffenen Pakete teilen sich eine Version.

export default defineConfig({
  versioning: "fixed",
});

Feste und gekoppelte Gruppen

Du kannst die meisten Pakete unabhängig lassen und nur ausgewaehlte Pakete gemeinsam verschieben:

export default defineConfig({
  versioning: "independent",
  fixed: [["@acme/core", "@acme/react"]],
  linked: [["@acme/cli", "@acme/config"]],
});

• fixed: alle Pakete in der Gruppe landen auf exakt derselben Version
• linked: der hoechste Versionssprung wird über die Gruppe hinweg propagiert

Snapshot-Einstellungen

Snapshots eignen sich für Preview-Releases und branch-spezifische Validierung.

export default defineConfig({
  snapshotTemplate: "{tag}-{timestamp}",
});

Beispielausgabe:

• 0.4.1-snapshot-20260312T102233

Plugins

Fuege Plugins über das plugins-Array hinzu:

import { defineConfig } from "@pubm/core";
import { externalVersionSync } from "@pubm/plugin-external-version-sync";

export default defineConfig({
  plugins: [
    externalVersionSync({
      targets: [
        {
          file: "README.md",
          pattern: /pubm@([\\w.-]+)/,
        },
      ],
    }),
  ],
});

Lies die Plugins API Reference für Hook-Reihenfolge, Command-Registrierung und Unterstützung benutzerdefinierter Registries.

Beispielmuster

Einfache Bibliothek

Wenn das Paket package.json und jsr.json (oder deno.json / deno.jsonc) hat, werden Registries automatisch abgeleitet. Eine Config-Datei ist nicht nötig - pubm.config.ts ist optional. Erstelle sie nur, wenn du einen Standardwert überschreiben musst (z. B. eigener Branch, Plugins, Release-Artefakte usw.).

App-Monorepo

Pakete mit nur package.json werden als npm aufgeloest. Explizite registries brauchst du nicht, außer du willst sie überschreiben.

import { defineConfig } from "@pubm/core";

export default defineConfig({
  versioning: "fixed",
  packages: [
    { path: "packages/web" },
    { path: "packages/server" },
  ],
});

Gemischter JS- und Rust-Workspace

import { defineConfig } from "@pubm/core";

export default defineConfig({
  versioning: "independent",
  packages: [
    { path: "packages/sdk" },
    { path: "crates/sdk-core" },
  ],
});

Release-Artefakte

releaseAssets beschreibt die Binärartefakte, die an jeden GitHub Release angehaengt werden sollen. Für die meisten Faelle reicht ein einfacher Glob-String:

import { defineConfig } from "@pubm/core";

export default defineConfig({
  releaseAssets: [
    "platforms/*/bin/mytool",
  ],
});

compress

• Typ: "tar.gz" | "zip" | "tar.xz" | "tar.zst" | false | Record<string, CompressFormat>
• Standard: OS-abhängige Auto-Erkennung (Windows -> zip, sonst -> tar.gz)

Globales Standard-Komprimierungsformat. Kann innerhalb von releaseAssets auf Gruppen- oder Dateiebene ueberschrieben werden.

export default defineConfig({
  // Für Windows zip, sonst tar.gz
  compress: { windows: "zip" },

  releaseAssets: [
    "platforms/*/bin/mytool",
  ],
});

releaseAssets

• Typ: (string | ReleaseAssetGroupConfig)[]
• Standard: undefined (keine angehaengten Assets)

Jeder Eintrag ist entweder ein Glob-String oder ein Objekt mit expliziter Steuerung:

releaseAssets: [
  // String: Glob, vollautomatisch
  "platforms/*/bin/mytool",

  // Objekt: explizite Einstellungen pro Gruppe
  {
    packagePath: "packages/cli",    // Monorepo: Release dieses Pakets verknuepfen
    files: [
      "platforms/*/bin/mytool",
      { path: "dist/*.dmg", compress: false, name: "MyTool-{version}-{os}" },
    ],
    compress: "tar.gz",             // Gruppenstandard
    name: "{name}-{platform}",      // Gruppen-Vorlage für Namen
  },
]

Lies den Leitfaden Release Assets für die vollständigen Regeln der Komprimierungs-Kaskade, Variablen für Name-Vorlagen und Anwendungsbeispiele.

Versionsquellen

pubm changesets version kann Versions-Bumps aus zwei Quellen auflösen: Changeset-Dateien in .pubm/changesets/ und Conventional-Commit-Nachrichten. Du kannst steuern, welche Quellen aktiv sind und wie Commit-Typen Bump-Ebenen zugeordnet werden.

versionSources

• Typ: "all" | "changesets" | "commits"
• Standard: "all"

Steuert, welche Quellen pubm changesets version bei der Berechnung von Versions-Bumps liest.

Wert	Verhalten
"all"	Verwendet Changesets für Pakete, die welche haben. Fällt für Pakete ohne ausstehende Changesets auf Conventional Commits zurück.
"changesets"	Liest nur .pubm/changesets/-Dateien. Conventional Commits werden ignoriert.
"commits"	Liest nur Conventional-Commit-Nachrichten. Changeset-Dateien werden ignoriert.

conventionalCommits

Konfiguriert, wie Commit-Typ-Präfixe auf Semver-Bump-Ebenen abgebildet werden. Gilt nur, wenn versionSources "all" oder "commits" ist.

export default defineConfig({
  versionSources: "all",
  conventionalCommits: {
    types: {
      // Typen hinzufügen, die standardmäßig ignoriert werden
      refactor: "patch",
      docs: "patch",
    },
  },
});

Die Standard-Zuordnung lautet:

Commit-Typ	Bump
feat	minor
fix	patch
perf	patch

Commits mit BREAKING CHANGE im Footer oder einem !-Suffix (z. B. feat!:) erzeugen immer einen major-Bump, unabhängig von der Typ-Zuordnung.

Commit-Typen, die nicht in der Zuordnung aufgeführt sind (z. B. chore, docs, test, ci, style, refactor), werden bei der Bump-Berechnung ignoriert. Du kannst jeden Typ im types-Objekt überschreiben — zum Beispiel würde refactor: "patch" Refactor-Commits als Patch-Bumps behandeln.

Naechste Schritte

• Verwende den Leitfaden Monorepo, wenn du Paket-Gruppierung oder gemischte Registries brauchst.
• Verwende die Plugins API Reference, wenn deine Config benutzerdefinierte Plugins registriert.
• Verwende den Leitfaden Release Assets, um Binaries und Archive an GitHub Releases anzuhaengen.
• Lies den Leitfaden Changesets für mehr Informationen zum Fallback auf Conventional Commits.