Options du plugin

Tous les réglages sont passés à la fabrique du plugin dans vite.config.ts. L'exemple ci-dessous liste toutes les options :

import { DEFAULT_COLORS } from "@mars-tech/vite-debug-plugin/helpers";

mtDebug({
  enabled: true,
  levels: ["error", "warning", "info", "debug", "success", "trace"],
  // minLevel: "debug", // ignoré quand `levels` est aussi défini (voir plus bas)
  terminal: true,
  browser: true,
  showSourceLocation: true,
  prefix: "MARS-TECH",
  colors: {
    warning: { ...DEFAULT_COLORS.warning, label: "Warn" },
  },
  globalName: "$debug",
  prefixFilter: "-NoisyLib",
  stripInDeps: ["@your-org/some-pinia-plugin"],
  allowDebugBuild: false,
  libraryPrefix: false,
  redact: [/x-api-key: \S+/, "supersecret"],
  redactDefaults: false,
  testStub: true,
  testLog: false,
});

Option	Type	Défaut
enabled	boolean	actif sous vite dev, inactif sous vite build
levels	MTLevel[]	tous les niveaux
minLevel	MTLevel	non défini
terminal	boolean	true
browser	boolean	true
showSourceLocation	boolean	true
prefix	string	'MARS-TECH'
colors	Partial<MTColorMap>	non défini
globalName	string	'$debug'
prefixFilter	string	non défini
stripInDeps	(string | RegExp)[]	[]
allowDebugBuild	boolean	false
libraryPrefix	boolean	false
redact	(string | RegExp)[]	[]
redactDefaults	boolean	false
testStub	boolean	true
testLog	boolean	false

enabled

Interrupteur principal. Par défaut, le plugin est actif quand Vite sert l'application (vite dev, où le plugin vérifie command === 'serve') et inactif sous vite build, quelle que soit la valeur de --mode.

false désactive le plugin sous vite dev : aucun environnement d'exécution n'est injecté et les appels $debug sont retirés, sauf avec allowDebugBuild: true, où, en 0.6, les appels restent en place et lèvent une ReferenceError. Sous Vitest, enabled: false n'empêche pas testStub / testLog. true ne permet pas de l'activer dans un build.

Remarque

Le README de la 0.6.1 indique comme valeur par défaut mode === 'development'. Le plugin vérifie en réalité la commande Vite : vite build --mode development retire donc bien tous les appels.

levels

Liste blanche des niveaux à conserver.

Si levels et minLevel sont tous deux définis, le plugin affiche un avertissement au chargement de la config Vite, et une liste levels non vide l'emporte : minLevel est ignoré. Un tableau levels vide équivaut à ne pas le définir.

minLevel

Seuil (trace < debug < info < success < warning < error) : conserve le niveau indiqué et tous les niveaux supérieurs. Ignoré quand une liste levels non vide est définie.

Le navigateur et le serveur peuvent relever ce seuil à l'exécution, jamais descendre sous le jeu de niveaux du build : voir Espaces de noms et filtrage.

terminal

Imprime sur la sortie standard de Vite, le terminal du serveur de développement. À false, les lignes loguées dans le navigateur ne sont plus transmises au terminal.

En 0.6, l'environnement d'exécution injecté automatiquement dans les modules rendus côté serveur (virtual:mt-debug/ssr, voir SSR) écrit sur process.stdout quelle que soit cette option.

browser

Imprime dans la console du navigateur.

showSourceLocation

Valeur par défaut de l'option d'appel showSource (voir la signature de la fonction).

En 0.6, l'emplacement désigne le plugin

En 0.6, l'emplacement (fichier:ligne:colonne) affiché est une ligne du code du plugin lui-même (dans le navigateur, /@mars-tech-vite-debug/runtime) et jamais l'endroit de votre appel, côté navigateur comme côté serveur. La version 1.0 corrige ce défaut.

prefix

Préfixe affiché en tête de chaque ligne. Un appel peut le remplacer avec l'option d'appel prefix, et une bibliothèque peut garder son propre préfixe dans l'application qui la consomme avec libraryPrefix.

colors

Surcharges de couleur par niveau ; les clés manquantes retombent sur les valeurs par défaut listées dans Niveaux. Chaque entrée de niveau a trois champs : ansi (la fonction qui colore la sortie du terminal), css (la couleur dans la console du navigateur) et label.

En 0.6, les lignes écrites par l'environnement d'exécution SSR (virtual:mt-debug/ssr) gardent les couleurs de terminal par défaut : seules les surcharges de label s'y appliquent.

Fusion des surcharges de couleur

L'option colors fournie par l'utilisateur fusionne en profondeur, niveau par niveau :

mtDebug({
  colors: {
    error: { label: "Error123" },
  },
});

Résout en :

{
  error: { ansi: red, css: '#ef4444', label: 'Error123' },
  // les autres niveaux ne sont pas touchés
}

TypeScript en 0.6

En 0.6, le type de colors exige les trois champs (ansi, css, label) pour chaque niveau surchargé. Une surcharge du seul libellé fusionne correctement à l'exécution mais échoue à la vérification de types. Étalez l'entrée par défaut pour rester valide :

import { DEFAULT_COLORS } from "@mars-tech/vite-debug-plugin/helpers";

mtDebug({
  colors: {
    error: { ...DEFAULT_COLORS.error, label: "Error123" },
  },
});

globalName

Identifiant attaché à globalThis. Le retrait des appels en production cible cet identifiant (voir Comportement en production).

globalName personnalisé

Si vous changez globalName, le fichier .d.ts livré ne correspond plus. Ajoutez votre propre augmentation :

// src/vite-env.d.ts
import type {
  MTLevel,
  MTCallOptions,
} from "@mars-tech/vite-debug-plugin/helpers";

declare global {
  function myDebug<T>(
    level: MTLevel,
    payload: string | Error | T,
    options?: MTCallOptions,
  ): void;
}

export {};

Cette déclaration type l'appel lui-même. Les types /client livrés déclarent var $debug: MTDebug ; pour typer aussi les contrôles à l'exécution et les fonctions utilitaires (ns, enable, time…) sous votre nom, déclarez plutôt var myDebug: MTDebug, en important MTDebug depuis @mars-tech/vite-debug-plugin/helpers.

Renommer la globale touche aussi les autres intégrations :

• ESLint : la config plate par défaut ne déclare que $debug. Utilisez plutôt la fabrique : mtDebugFlatConfig({ globalName: "myDebug" }) depuis @mars-tech/vite-debug-plugin/eslint (.eslintrc historique : { globals: mtDebugGlobals("myDebug") }). Voir Utilisation.
• Vitest : le bouchon sans effet automatique n'installe que $debug. Mettez testStub: false et appelez installMtDebugStub({ globalName: "myDebug" }) depuis un fichier de configuration (voir Tests). Avec testLog: true, le journaliseur enregistré automatiquement, qui écrit dans la console, utilise votre nom personnalisé.

prefixFilter

Filtre de préfixe par défaut, fixé au build : coupe ou isole les logs selon leur préfixe affiché (syntaxe du paquet debug). Remplacé par ?mt-debug-prefix=, localStorage, MT_DEBUG_PREFIX et $debug.setPrefixFilter(...). Voir Filtrage par préfixe.

stripInDeps

Soumet certains paquets de node_modules à la transformation qui retire les appels en production. Solution de repli pour les bibliothèques qui ne livrent pas leur propre double variante (voir Création de bibliothèque).

Par défaut, le plugin ignore tout module dont le chemin contient node_modules : les appels $debug(...) figés dans une bibliothèque publiée subsistent dans le build de l'application qui la consomme. Une entrée de type chaîne correspond à tout chemin de module qui la contient (un simple nom de paquet suffit) ; une RegExp est testée sur le chemin du module. Les définitions de types recommandent de l'associer à optimizeDeps.exclude pour les mêmes paquets, afin que Vite les serve sous forme de modules source que la transformation voit de façon fiable.

allowDebugBuild

Mode bibliothèque : vite build émet une double sortie (dist/ sans les appels, et dist/debug/ avec les appels conservés et un shim de secours ajouté automatiquement en tête). Voir Création de bibliothèque avec allowDebugBuild.

libraryPrefix

Mode bibliothèque : appose le prefix de la bibliothèque sur ses appels $debug pour qu'ils restent marqués une fois consommés, au lieu d'hériter du préfixe de l'application. Nécessite allowDebugBuild. Voir Marquer les logs de bibliothèque avec libraryPrefix.

redact

Masque les correspondances dans le message rendu ([redacted]), dans le navigateur comme dans le terminal. Les chaînes correspondent littéralement ; une RegExp est appliquée globalement et peut conserver un groupe $1. Voir Masquer les secrets.

redactDefaults

Applique aussi un jeu de motifs sensibles (JWT, jetons Bearer, adresses e-mail, clés sk_/pk_, valeurs JSON secrètes). Voir Masquer les secrets.

testStub

Sous Vitest, enregistre automatiquement en tête de setupFiles une entrée qui installe un $debug sans effet (globale par défaut uniquement). Mettez false pour le gérer vous-même. Jest, et les configs Vitest qui n'incluent pas ce plugin, ajoutent plutôt @mars-tech/vite-debug-plugin/testing à setupFiles. Voir Tests.

testLog

Sous Vitest, fait installer par ce fichier de configuration automatique un vrai journaliseur console qui tient compte de la configuration au lieu de la fonction vide : les appels $debug(...) des composants et des fichiers de test s'affichent avec vos prefix, globalName et levels configurés. Nécessite testStub actif. En 0.6, ce journaliseur n'applique ni redact ni redactDefaults, utilise les libellés et les couleurs par défaut et n'affiche ni emplacement source ni pile d'appels. Voir Voir la sortie $debug dans les tests.