Configuration

pubm est volontairement CLI-first, mais les vrais projets dépassent vite une configuration limitée aux flags. pubm.config.* est l’endroit où vous gardez les cibles de publication au niveau du dépôt, le layout des packages, les plugins et les règles de versioning liées aux changesets.

Exécutez pubm init pour générer ce fichier de configuration de manière interactive. L’assistant ne crée un fichier de config que si vos choix diffèrent des valeurs par défaut indiquées ci-dessous.

Fichiers de configuration pris en charge

pubm prend en charge les noms de fichiers suivants :

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

Les fichiers de configuration TypeScript sont pris en charge directement. Le loader bundle le fichier avant l’évaluation, donc vous n’avez pas besoin d’une étape séparée de transpilation au runtime.

Configuration par défaut

Voici les valeurs par défaut résolues par la couche de configuration :

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",
});

Comment les registries sont inférés

pubm inspecte les fichiers manifest dans chaque répertoire de package et les associe à des registries :

Manifest	Registry inféré
package.json	npm
jsr.json	jsr
deno.json / deno.jsonc	jsr
Cargo.toml	crates

Deux règles supplémentaires s’appliquent à npm :

• publishConfig.registry dans package.json remplace npm par cette URL personnalisée
• le registry .npmrc remplace npm lorsque publishConfig est absent

Options de niveau supérieur

versioning

• Type : "independent" | "fixed"
• Par défaut : "independent"

Contrôle la manière dont les versions sont attribuées dans les dépôts multi-package.

branch

• Type : string
• Par défaut : "main"

Branche qui doit correspondre à HEAD pendant les exécutions de release protégées.

packages

• Type : PackageConfig[]
• Par défaut : [{ path: "." }]

Déclare explicitement les packages publiables. Les registries sont inférés à partir des fichiers manifest, sauf si vous les surcharger par package.

plugins

• Type : PubmPlugin[]
• Par défaut : []

Enregistre les plugins capables d’ajouter des hooks, des commandes, des registries ou des écosystèmes.

fixed

• Type : string[][]
• Par défaut : []

Groupes de packages qui doivent toujours aboutir à la même version.

linked

• Type : string[][]
• Par défaut : []

Groupes de packages qui doivent partager le type de bump le plus élevé.

ignore

• Type : string[]
• Par défaut : []

Noms ou chemins de packages à exclure de la découverte du workspace.

tag

• Type : string
• Par défaut : "latest"

Dist-tag par défaut pour les exécutions de publication.

contents

• Type : string
• Par défaut : "."

Répertoire dans lequel faire chdir avant d’exécuter le pipeline de release.

saveToken

• Type : boolean
• Par défaut : true

Indique si les tokens de registry pris en charge doivent être stockés pour réutilisation sur les machines locales.

releaseDraft

• Type : boolean
• Par défaut : true

Indique si le flux de publication doit créer une GitHub Release. Lorsqu’il est désactivé, l’étape de release est entièrement ignorée.

excludeRelease

• Type : string[]
• Par défaut : []

Motifs glob pour les packages qui doivent être versionnés et publiés, mais exclus de la création de tags git et des brouillons de GitHub Release. S’applique uniquement quand versioning est "independent".

Utilisez cette option pour les artefacts de build internes, comme les binaires spécifiques à une plateforme, qui sont publiés dans un registre mais ne doivent pas apparaître comme des releases autonomes.

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

validate

• Type : ValidateConfig

Ces champs font partie du schéma public, mais ils ne sont pas encore des bascules actives sur tous les chemins de publication. Considérez-les comme une surface de config typée, pas comme des interrupteurs runtime garantis.

snapshotTemplate

• Type : string
• Par défaut : "{tag}-{timestamp}"

Modèle utilisé quand pubm --snapshot génère une chaîne de version temporaire.

Variables de modèle disponibles :

• {base} : version actuelle du package issue du manifest
• {tag} : tag de snapshot, par défaut snapshot
• {timestamp} : timestamp UTC au format YYYYMMDDTHHmmss
• {commit} : SHA du commit Git courant

Dans les projets monorepo avec versioning fixed, le template est appliqué une seule fois en utilisant la version du premier package comme {base}. Avec le versioning independent, chaque package génère sa propre version snapshot en utilisant son propre {base}.

createPr

• Type : boolean
• Par défaut : false

Crée une pull request pour le commit de version bump au lieu de pousser directement vers la branche de base. Lorsque activé, pubm crée une branche pubm/version-packages-*, la pousse et ouvre une PR. Le workflow de release se déclenche normalement lorsque la PR est fusionnée.

pubm bascule également automatiquement en mode PR lorsqu’un push direct vers une branche protégée échoue.

locale

• Type : "en" | "ko" | "zh-cn" | "fr" | "de" | "es"
• Par défaut : "en"

Langue de sortie de la CLI. Peut également être définie via le flag --locale ou la variable d’environnement PUBM_LOCALE. Ordre de résolution : flag --locale → variable d’environnement PUBM_LOCALE → config → locale système → "en".

rollback

Contrôle le comportement du rollback en cas d’échec de publication.

Clé	Type	Par défaut	Description
strategy	"individual" | "all"	"individual"	Granularité du rollback. Remplace le champ obsolète rollbackStrategy de niveau supérieur.
dangerouslyAllowUnpublish	boolean	false	Autorise le unpublish/yank du registry lors du rollback dans les environnements sans TTY (CI). Même après un unpublish, npm réserve définitivement le numéro de version : il ne peut pas être réutilisé.

export default defineConfig({
  rollback: {
    strategy: "individual",
    dangerouslyAllowUnpublish: true, // activer pour CI
  },
});

Le champ obsolète rollbackStrategy de niveau supérieur fonctionne toujours et correspond à rollback.strategy. Si les deux sont définis, rollback.strategy a la priorité.

Interaction entre la config et les flags CLI

Le comportement runtime actuel est le suivant :

• la config fournit les valeurs par défaut du dépôt pour packages et plugins
• la config liée au versioning, comme versioning, fixed et linked, est utilisée par les flux de changesets
• les flags CLI contrôlent toujours le comportement de publication pour chaque exécution
• les registries sont inférés à partir des manifests ; packages[].registries remplace cette inférence

Pour une publication ponctuelle vers un registry précis :

pubm --registry npm --tag beta

Configuration multi-package

Pour les workspaces ou les dépôts mélangeant plusieurs langages, déclarez les packages explicitement. Les registries sont inférés à partir des fichiers manifest de chaque package :

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

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

Utilisez des entrées de package explicites quand :

• vous voulez que pubm ne publie qu’un sous-ensemble des packages du workspace découverts
• des packages JavaScript et Rust vivent dans le même dépôt
• vous devez remplacer des registries inférés ou ajouter des registries privés

PackageConfig

Les entrées au niveau du package ont cette forme :

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

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

Utilisez registries uniquement lorsque l’inférence ne suffit pas ou lorsque vous devez ajouter des registries privés à côté des registries intégrés :

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

Stratégies de versioning

Versioning indépendant

Chaque package obtient sa propre version et son propre tag.

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

Versioning fixe

Chaque package concerné partage une seule version.

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

Groupes fixed et linked

Vous pouvez garder la plupart des packages indépendants tout en forçant certains packages à évoluer ensemble :

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

• fixed : tous les packages du groupe aboutissent à exactement la même version
• linked : le type de bump le plus élevé se propage dans tout le groupe

Paramètres de snapshot

Les snapshots sont utiles pour les releases de prévisualisation et la validation spécifique à une branche.

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

Exemple de sortie :

• 0.4.1-snapshot-20260312T102233

Plugins

Ajoutez des plugins via le tableau plugins :

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.-]+)/,
        },
      ],
    }),
  ],
});

Lisez la Référence de l’API des plugins pour l’ordre des hooks, l’enregistrement des commandes et la prise en charge des registries personnalisés.

Exemples de configuration

Bibliothèque simple

Si le package a package.json et jsr.json (ou deno.json / deno.jsonc), les registries sont inférés automatiquement. Aucun fichier de config n’est nécessaire - pubm.config.ts est optionnel. Créez-le seulement lorsque vous devez remplacer un défaut (branche personnalisée, plugins, artefacts de release, etc.).

Monorepo d’application

Les packages avec seulement package.json sont résolus comme npm. Aucun registries explicite n’est nécessaire, sauf si vous voulez faire une surcharge.

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

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

Workspace mixte JS + Rust

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

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

Artefacts de release

releaseAssets déclare les artefacts binaires à attacher à chaque GitHub Release. Un simple motif glob suffit dans la plupart des cas :

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

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

compress

• Type : "tar.gz" | "zip" | "tar.xz" | "tar.zst" | false | Record<string, CompressFormat>
• Par défaut : auto-détection tenant compte de l’OS (windows → zip, autres → tar.gz)

Format de compression global par défaut. Peut être remplacé au niveau du groupe ou du fichier dans releaseAssets.

export default defineConfig({
  // Utilise zip pour Windows, tar.gz partout ailleurs
  compress: { windows: "zip" },

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

releaseAssets

• Type : (string | ReleaseAssetGroupConfig)[]
• Par défaut : undefined (aucun artefact attaché)

Chaque entrée est soit un motif glob, soit un objet offrant un contrôle explicite :

releaseAssets: [
  // Chaîne : glob, entièrement automatique
  "platforms/*/bin/mytool",

  // Objet : paramètres explicites par groupe
  {
    packagePath: "packages/cli",    // Monorepo : lier les artefacts à la release de ce package
    files: [
      "platforms/*/bin/mytool",
      { path: "dist/*.dmg", compress: false, name: "MyTool-{version}-{os}" },
    ],
    compress: "tar.gz",             // Valeur par défaut du groupe
    name: "{name}-{platform}",      // Modèle de nom du groupe
  },
]

Lisez le guide Artefacts de release pour les règles complètes de cascade de compression, les variables de modèles de nom et les exemples d’usage.

Sources de version

pubm changesets version peut résoudre les bumps de version à partir de deux sources : les fichiers de changeset dans .pubm/changesets/ et les messages de commits conventionnels. Vous pouvez contrôler quelles sources sont actives et comment les types de commits correspondent aux niveaux de bump.

versionSources

• Type : "all" | "changesets" | "commits"
• Défaut : "all"

Contrôle quelles sources pubm changesets version lit lors du calcul des bumps de version.

Valeur	Comportement
"all"	Utilise les changesets pour les packages qui en ont. Revient aux commits conventionnels pour les packages sans changesets en attente.
"changesets"	Ne lit que les fichiers .pubm/changesets/. Les commits conventionnels sont ignorés.
"commits"	Ne lit que les messages de commits conventionnels. Les fichiers de changeset sont ignorés.

conventionalCommits

Configure comment les préfixes de types de commits correspondent aux niveaux de bump semver. S’applique uniquement lorsque versionSources est "all" ou "commits".

export default defineConfig({
  versionSources: "all",
  conventionalCommits: {
    types: {
      // Ajouter des types ignorés par défaut
      refactor: "patch",
      docs: "patch",
    },
  },
});

La correspondance par défaut est :

Type de commit	Bump
feat	minor
fix	patch
perf	patch

Les commits avec BREAKING CHANGE dans le footer ou un suffixe ! (ex. feat!:) produisent toujours un bump major quelle que soit la correspondance de type.

Les types de commits non listés dans la correspondance (ex. chore, docs, test, ci, style, refactor) sont ignorés lors du calcul du bump. Vous pouvez redéfinir n’importe quel type dans l’objet types — par exemple, refactor: "patch" traiterait les commits refactor comme des bumps patch.

Étapes suivantes

• Utilisez le guide Monorepo si vous avez besoin d’un regroupement de packages ou de registries mixtes.
• Utilisez la Référence de l’API des plugins si votre config enregistre des plugins personnalisés.
• Utilisez le guide Artefacts de release pour attacher des binaires et des archives aux GitHub Releases.
• Consultez le guide Changesets pour en savoir plus sur le comportement de repli sur les commits conventionnels.