Création de bibliothèque avec allowDebugBuild

Si vous publiez une bibliothèque Vite qui utilise $debug en interne, vous voulez que le build publié contienne deux variantes parallèles : les consommateurs récupèrent les logs en développement sans en payer le coût en production. Le plugin produit les deux variantes en un seul build quand vous activez allowDebugBuild: true :

// vite.config.ts de B (la bibliothèque)
import mtDebug from "@mars-tech/vite-debug-plugin";

export default defineConfig({
  plugins: [mtDebug({ allowDebugBuild: true })],
  build: {
    lib: { entry: "src/index.ts", formats: ["es", "cjs"] },
    rollupOptions: { external: ["vue", "pinia"] },
    sourcemap: true,
  },
});

Sortie du build

Après vite build, le dist/ de la bibliothèque contient :

dist/
├── index.js          ← variante standard, chaque appel $debug retiré → éliminé (DCE)
├── index.cjs
├── index.d.ts        ← fichier de types unique partagé
├── index.js.map
├── index.cjs.map
└── debug/
    ├── index.js      ← variante debug, appels $debug conservés + shim de secours ajouté en tête
    ├── index.cjs
    ├── index.js.map
    └── index.cjs.map

Exports conditionnels

Câblez les exports conditionnels dans le package.json de la bibliothèque pour que Vite choisisse automatiquement la bonne variante :

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "development": {
        "import": "./dist/debug/index.js",
        "require": "./dist/debug/index.cjs"
      },
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

Si vous activez allowDebugBuild mais oubliez d'ajouter la condition development aux exports de votre package.json, le plugin émet un avertissement de build avec l'extrait exact à coller. Sans cette condition, la variante debug est générée mais jamais résolue, et les consommateurs n'ont pas de logs en développement.

Comportement à trois étages

Étage	Phase	Ce qui se passe
A plugin (ce paquet)	—	Fournit l'environnement d'exécution et la transformation qui produit les deux variantes.
B bibliothèque (par ex. un plugin Pinia)	vite build	allowDebugBuild: true → dist/index.* sans les appels, dist/debug/index.* garde les appels + shim de secours ajouté automatiquement en tête.
C application finale avec A	vite (développement)	Vite choisit la condition development → variante debug résolue → l'environnement d'exécution navigateur de A définit le vrai $debug en premier → le shim de secours n'y touche pas → les logs s'affichent.
C application finale avec A	vite build	Vite choisit la condition par défaut → variante standard résolue → aucune référence à $debug dans le bundle de C, quoi que C fasse dans son propre code.
C application finale sans A	vite (développement)	Variante debug résolue → le shim de secours installe un $debug sans effet et émet un console.warn unique conseillant d'installer A.
C application finale sans A	vite build	Variante standard résolue → appels déjà retirés → silencieux, aucun plantage.

Le shim de secours en 0.6

En 0.6, le shim de secours installe une fonction nue, sans aucune méthode. Dans une application qui ne charge pas le plugin, les appels de base ($debug(level, payload)) ne font rien et sont sans danger. En revanche, $debug.ns(...), assert, time/timeEnd, count, group/groupEnd, enable, disable, setLevel et setPrefixFilter lèvent une TypeError. Dans le code d'une bibliothèque, n'utilisez que les appels de base, ou construisez avec libraryPrefix: true : son $debug local protège toutes les méthodes sauf setPrefixFilter. Corrigé en 1.0.

Avec allowDebugBuild, les consommateurs n'ont rien à savoir de ce plugin. Les auteurs de bibliothèque n'écrivent pas de shim de secours à la main : le plugin l'ajoute automatiquement en tête de chaque chunk d'entrée de la variante debug.

Dépendance pair optionnelle

Déclarez le plugin dans le package.json de B comme dépendance pair (peerDependencies) optionnelle, pour que les consommateurs qui ne veulent pas de logs puissent quand même installer la bibliothèque :

{
  "peerDependencies": {
    "@mars-tech/vite-debug-plugin": ">=0.2.0"
  },
  "peerDependenciesMeta": {
    "@mars-tech/vite-debug-plugin": { "optional": true }
  }
}

Remarque

Pour les bibliothèques que vous ne pouvez pas reconstruire avec allowDebugBuild, l'application consommatrice peut retirer à son propre build les appels $debug figés dans une dépendance, grâce à l'option stripInDeps.

Marquer les logs de bibliothèque avec libraryPrefix

Par défaut, les appels $debug d'une bibliothèque s'affichent avec le préfixe de l'application consommatrice : c'est l'instance du plugin de l'application qui installe la globale $debug, et les appels nus de la bibliothèque héritent du préfixe configuré. Un log venant de votre bibliothèque apparaît donc comme App Info …, sans indiquer au développeur qu'il provient de votre bibliothèque.

Activez libraryPrefix: true (avec allowDebugBuild) pour que les logs de votre bibliothèque restent marqués de son propre préfixe partout où elle est utilisée :

// vite.config.ts de la bibliothèque
plugins: [
  mtDebug({ allowDebugBuild: true, libraryPrefix: true, prefix: "foo" }),
];

Chaque log de la bibliothèque s'affiche alors avec foo, quel que soit le préfixe de l'application consommatrice (ici, l'application est configurée avec prefix: "bar") :

foo Info [cart/action] - cart.add(Widget ×2)      ← depuis la bibliothèque
bar Info - user clicked checkout                  ← depuis l'application

Fonctionnement : la variante debug reçoit, en tête de chaque chunk, un petit $debug local au module qui masque la globale. Il relaie vers le vrai $debug de l'application mais impose { prefix } en dernière écriture : le préfixe de la bibliothèque ne peut pas être écrasé par le consommateur ni par une option d'appel. Votre code reste du $debug(...) simple : rien à retenir à chaque appel, rien que les consommateurs puissent désactiver. Si l'application consommatrice n'a aucun $debug, ce $debug local avertit une fois puis ne fait rien (et, contrairement au shim de secours de la 0.6, ns, assert et les fonctions utilitaires ne font rien non plus ; seul setPrefixFilter n'est pas protégé).

Les formes marquées sont l'appel de base, $debug.ns(...) et $debug.assert(...). Les fonctions utilitaires (time, count, group) ne prennent pas d'options d'appel : leur sortie garde le préfixe du consommateur.

Pour couper ou isoler une bibliothèque marquée dans l'application consommatrice, voir le filtrage par préfixe.