Options du plugin

Toutes les options à leur valeur par défaut ; celles qui ne sont pas définies par défaut figurent en commentaire. mtDebug() sans argument revient au même :

mtDebug({
  // enabled : non définie — actif en `vite dev`, inactif en `vite build`
  // levels, minLevel : non définies — tous les niveaux sont affichés (comme minLevel: "trace")
  // ils sont alternatifs : définir les deux avertit et garde levels
  output: {
    console: true,
    terminal: true,
    inspect: true,
    devtools: true, // écrite explicitement, avertit si @vue/devtools-api manque
    // file : non définie — `true` (.mt-debug/dev.ndjson) ou un chemin
    fileMaxBytes: 100 * 2 ** 20, // 100 Mio, dès que `file` est définie
  },
  showSource: true,
  prefix: "MARS-TECH",
  // colors : non définie — par ex. { warning: { label: "Warn" } }
  globalName: "$debug",
  // prefixFilter : non définie — par ex. "-NoisyLib"
  // filter : non définie — par ex. "cart:*"
  showStack: false,
  // library : non définie — par ex. { debugBuild: true, brandPrefix: true }
  redact: [],
  redactDefaults: false,
  test: "stub",
});

Récapitulatif

Option	Type	Valeur par défaut
`enabled`	`boolean`	non définie : actif en `vite dev`, inactif en `vite build`
`levels`	`MTLevel[]`	tous les niveaux
`minLevel`	`MTLevel`	non définie
`output`	`{ console?, terminal?, inspect?, devtools?, file?, fileMaxBytes? }`	toutes les sorties activées, sauf `file`
`showSource`	`boolean`	`true`
`prefix`	`string`	`'MARS-TECH'`
`colors`	`MTColorOverrides`	non définie
`globalName`	`string`	`'$debug'`
`prefixFilter`	`string`	non définie
`filter`	`string`	non définie
`showStack`	`boolean`	`false`
`library`	`{ debugBuild: boolean; brandPrefix?: boolean }`	non définie
`redact`	`(string \| RegExp)[]`	`[]`
`redactDefaults`	`boolean`	`false`
`test`	`false \| 'stub' \| 'log'`	`'stub'`

Plusieurs options ont été renommées dans la 1.0.0. Les anciens noms fonctionnent encore, avec un avertissement, jusqu'à la 2.0, mais un vite.config.ts vérifié par TypeScript les signale comme des erreurs : voir Migrer depuis la 0.6. stripInDeps a été retirée et ne supprime plus aucun appel. L'avertissement qu'elle affiche se termine par « See MIGRATION.md for the migration » : la solution de remplacement se trouve sous stripInDeps dans le guide de migration.

`enabled`

Type boolean. Valeur par défaut : non définie, ce qui suit la commande Vite.

Interrupteur principal, basé sur la commande Vite : actif en vite dev, inerte en vite build. Il ne dépend pas de mode : vite build --mode development reste donc inerte.

false désactive le plugin : aucun environnement d'exécution n'est servi ni injecté, l'API de Vue DevTools n'est pas pré-optimisée, et test: 'log' retombe sur le bouchon inerte. Les appels $debug sont malgré tout supprimés de vos sources : le code de développement désactivé ne peut donc pas lever d'erreur. Avec output.file définie, le serveur de développement refuse encore ce chemin à la page, car un log laissé par une session précédente peut encore se trouver sur le disque.

true ne force pas l'environnement d'exécution de développement dans un build de production ; utilisez library.debugBuild pour cela. Passer true explicitement ne change rien.

C'est aussi le plugin qui supprime les appels en vite build : enregistrez-le donc sans condition, dans le tableau plugins de premier niveau. Voir Installer et enregistrer le plugin. Enregistré sous build.rollupOptions.plugins, ou dans une configuration Rollup ou Rolldown, il supprime les appels comme en vite build, sans avertissement.

`levels`

Type MTLevel[]. Valeur par défaut : tous les niveaux.

Liste des niveaux affichés. Si levels et minLevel sont tous deux définis, une liste levels non vide l'emporte et minLevel est ignoré, avec un avertissement au démarrage. Une liste vide levels: [] laisse la main à minLevel, sans avertissement. Les noms des niveaux sont listés dans Niveaux.

`minLevel`

Type MTLevel. Valeur par défaut : non définie.

Seuil : chaque niveau supérieur ou égal est conservé (trace < debug < info < success < warning < error).

`output`

Type { console?, terminal?, inspect?, devtools?, file?, fileMaxBytes? }. Valeur par défaut : toutes les sorties activées, sauf file.

Où la sortie apparaît. Chaque clé active une sortie, sauf fileMaxBytes :

console : la console du navigateur.
terminal : le terminal Vite. Les appels du navigateur y sont transmis, et les appels SSR et du processus Vite y sont imprimés. false le fait taire partout ; $debug reste défini.
inspect : navigateur uniquement. Transmet aussi la charge utile brute à la console comme argument vivant et inspectable. L'option d'appel { inspect } prend le dessus : voir Inspection d'objets vivante.
devtools : Vue et Nuxt uniquement. Affiche chaque appel dans Vue DevTools. Nécessite la dépendance pair optionnelle @vue/devtools-api, installée dans un node_modules situé à la racine Vite ou au-dessus. Sans elle, l'intégration est laissée de côté, et un devtools: true explicite avertit à chaque démarrage du serveur de développement : voir Vue DevTools.
file : écrit aussi chaque appel comme une ligne NDJSON (MTLogLine) dans un fichier. Pas quand votre code logue des secrets, même masqués : voir Fichier de log NDJSON. true écrit dans .mt-debug/dev.ndjson sous la racine Vite ; une chaîne est un chemin, relatif à la racine ou absolu. false, null ou l'absence de valeur laissent le fichier désactivé, donc file: process.env.MT_LOG === "1" sert d'interrupteur ; toute autre valeur avertit et le laisse désactivé. Il y a une session par fichier, écrite après masquage, et les appels du navigateur sont inclus même avec terminal: false. Le fichier n'est pas ouvert sous Vitest. Le plugin tient le log à l'écart de la page, mais c'est un filet de sécurité, pas un coffre-fort : un log que vous gardez est plus sûr hors du projet (hors de server.fs.allow). À côté de certains outils de développement qui lisent n'importe quel fichier pour la page, le log reste désactivé. Voir Tenir le log à l'écart de la page, et Fichier de log NDJSON pour le format des lignes.
fileMaxBytes : la taille maximale du fichier de log sur une session, en octets, dernière ligne comprise. Valeur par défaut : 100 Mio. Une fois la limite atteinte, une dernière ligne de niveau warning le signale, le terminal reçoit un avertissement, et ce serveur de développement n'écrit plus rien dans le fichier avant son redémarrage. Infinity lève la limite ; null, comme une option non définie, garde la valeur par défaut ; toute autre valeur qui n'est pas un nombre supérieur à 0 avertit et garde la valeur par défaut. Voir Sessions et taille.

Avec console, terminal et devtools tous désactivés et sans file, un $debug inerte est servi à la place de l'environnement d'exécution : vos appels ne lèvent donc toujours pas d'erreur.

output remplace les indicateurs de la 0.6 browser (devenu console) et terminal ; les clés à plat inspect et devtools utilisées pendant le développement de la 1.0 sont aussi encore acceptées. Les quatre fonctionnent, avec un avertissement, jusqu'à la 2.0. Voir Où apparaît la sortie.

`showSource`

Type boolean. Valeur par défaut : true.

Affiche le fichier:ligne:colonne de chaque appel : le fichier relatif à la racine Vite, avec la ligne et la colonne comptées à partir de 1, identique sur chaque sortie. L'option d'appel showSource prend le dessus, appel par appel.

Pour un appel que la transformation de développement marque, la localisation affichée est celle de la source d'origine : elle est capturée au moment de la transformation depuis la source map combinée, donc elle fonctionne à travers la compilation des composants monofichiers .vue, côté client comme côté SSR (Nuxt compris), au lieu de pointer vers la position transpilée dans la pile. Un appel qu'elle ne peut pas marquer (un journaliseur renvoyé par ns(), conservé et appelé plus tard, count(), timeEnd(), assert() et, côté serveur, les libellés de group(), table() et dir()) prend sa position dans la pile de l'environnement d'exécution, qui peut être décalée de quelques lignes dans du code compilé : appelez $debug(...) directement là où la ligne exacte compte. Voir Le fichier:ligne de mon log est décalé de quelques lignes.

Cette option s'appelait showSourceLocation avant la 1.0.0. L'ancien nom fonctionne encore, avec un avertissement, jusqu'à la 2.0.

`prefix`

Type string. Valeur par défaut : 'MARS-TECH'.

Le préfixe au début de chaque ligne affichée, par exemple MARS-TECH Warning [PropsValidator] - Invalid variant "danger". Remplacez-le par le nom de votre application ou de votre bibliothèque. Un appel peut le remplacer ponctuellement avec l'option d'appel prefix.

`colors`

Type MTColorOverrides. Valeur par défaut : non définie.

Surcharges, niveau par niveau, du libellé, de la couleur CSS du navigateur et de la couleur du terminal. N'importe quel sous-ensemble de niveaux est accepté, chacun avec n'importe quel sous-ensemble des champs ansi, css et label ; les clés absentes retombent sur les valeurs par défaut listées dans Niveaux.

Fusion des surcharges de couleur

Les colors fournies par l'utilisateur sont fusionnées en profondeur, niveau par niveau :

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

Résultat :

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

ansi s'applique sur toutes les sorties terminal, à une condition

La sortie côté serveur (rendus SSR, $debug appelé depuis vite.config.ts ou depuis un autre plugin) provient d'un environnement d'exécution généré qui ne peut pas importer votre fonction. Le plugin appelle donc chaque ansi surchargé une seule fois, au chargement de la configuration, sur une chaîne témoin, capture les codes d'échappement placés autour, et transmet ces codes à l'environnement d'exécution. Toute fonction de coloration ordinaire (kolorist, picocolors, chalk, ou (s) => "\x1b[35m" + s + "\x1b[39m") est capturée exactement. Une fonction qui ne renvoie pas son entrée telle quelle dans le résultat (qui la met en majuscules, la tronque ou la complète) n'a aucun code à capturer : ce niveau garde la couleur intégrée côté serveur, tandis que votre fonction s'applique toujours au chemin du navigateur vers le terminal, qui l'appelle directement. label et css ne sont affectés nulle part.

`globalName`

Type string. Valeur par défaut : '$debug'.

Identifiant attaché à globalThis, par exemple mtDebug({ globalName: "myDebug" }). La suppression des appels en production vise le même identifiant. Ce doit être un identifiant JavaScript valide qui n'est pas un mot réservé ($debug, myDebug, 日志) ; avec toute autre valeur, par exemple un nom avec un point, une espace ou un tiret, mtDebug() lève une erreur au démarrage.

`globalName` personnalisé côté application

Si vous changez globalName, le fichier .d.ts client fourni ne correspond plus. Ajoutez votre propre augmentation de type :

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

declare global {
  // eslint-disable-next-line no-var
  var myDebug: MTDebug;
}

export {};

Déclarez-la comme MTDebug

Déclarez-la comme MTDebug, pas comme une simple function. MTDebug est la fonction appelable intersectée avec les 14 méthodes : myDebug.ns(...), .table(...) et la surcharge variadique gardent donc leurs types, alors qu'une simple déclaration de fonction les perd toutes silencieusement. C'est ce que fait le client.d.ts fourni.

Un renommage touche aussi les autres outils qui connaissent la globale par son nom :

ESLint : utilisez la fabrique nommée mtDebugFlatConfig({ globalName: "myDebug" }) de @mars-tech/vite-debug-plugin/eslint au lieu de l'export par défaut. Voir Déclarer la globale à ESLint.
Vitest : le bouchon inerte automatique n'installe que $debug. Réglez test: false et appelez installMtDebugStub({ globalName: "myDebug" }) de @mars-tech/vite-debug-plugin/testing dans un fichier de configuration des tests. Voir Bouchon programmatique.
Avec test: 'log', le nom personnalisé est pris en compte sans configuration supplémentaire.

`prefixFilter`

Type string. Valeur par défaut : non définie.

Filtre de préfixe par défaut, fixé au build : fait taire ou isole les logs selon leur préfixe affiché, avec une syntaxe façon debug. Il est remplacé par le paramètre d'URL ?mt-debug-prefix= et par localStorage dans le navigateur, par la variable d'environnement MT_DEBUG_PREFIX côté serveur, et par $debug.setPrefixFilter(...). Voir Filtrage par préfixe.

`filter`

Type string. Valeur par défaut : non définie. Nouveauté de la 1.0.0.

Filtre d'espaces de noms par défaut, fixé au build, avec la même syntaxe façon debug que $debug.enable() (cart*, -noisy, auth,cart:*). Il est remplacé par le paramètre d'URL ?mt-debug= et par localStorage dans le navigateur, par MT_DEBUG côté serveur, et par $debug.enable(pattern) à l'exécution ; $debug.enable(null) y revient. Voir Espaces de noms et filtrage à l'exécution.

`showStack`

Type boolean. Valeur par défaut : false. Nouveauté de la 1.0.0.

Valeur par défaut de l'option d'appel showStack : joint la pile (masquée) de l'Error à chaque appel qui en porte une. { showStack: false } permet toujours d'exclure un appel.

`library`

Type { debugBuild: boolean; brandPrefix?: boolean }. Valeur par défaut : non définie.

Création de bibliothèque. debugBuild: true fait produire à vite build une double sortie : dist/, dont chaque appel est supprimé, et dist/debug/, qui garde les appels et reçoit en tête une solution de secours qui s'installe d'elle-même. brandPrefix: true appose en plus le prefix de la bibliothèque sur ses appels $debug, qui restent ainsi marqués dans l'application consommatrice ; sans debugBuild, ce réglage n'a aucun effet, et le plugin avertit.

Seul le préfixe voyage : vos redact et redactDefaults ne sont pas livrés dans dist/debug/, c'est donc la configuration de l'application consommatrice qui masque la sortie de votre bibliothèque. Ne passez jamais de secret à $debug dans le code d'une bibliothèque : voir Le masquage appartient à l'application consommatrice.

library remplace allowDebugBuild et libraryPrefix. Les deux fonctionnent encore, avec un avertissement, jusqu'à la 2.0. Voir Création de bibliothèque.

`redact`

Type (string | RegExp)[]. Valeur par défaut : [].

Remplace les correspondances par [redacted]. Chaque règle s'applique à chaque chaîne qu'un appel remet au plugin (charges utiles, piles d'Error, espaces de noms et tags, préfixes d'appel, libellés des utilitaires, chemin de la source) et à la ligne affichée, et masque chaque correspondance en entier. L'endroit où une entrée s'applique dépend de son type :

Une RegExp s'applique sur toutes les sorties : la console du navigateur, le terminal de développement, la sortie SSR, le fichier de log, Vue DevTools et test: 'log'. Elle est envoyée telle quelle à la page : elle doit donc décrire la forme d'un secret, jamais contenir le secret. Elle est appliquée globalement (le drapeau y est retiré), et un groupe de capture ne garde rien de sa correspondance (la convention $1 de la 0.6 a disparu) : pour garder le texte qui précède un secret, faites-le correspondre avec une assertion arrière ((?<=…)).
Une chaîne correspond littéralement, à chaque occurrence, côté serveur uniquement : le terminal de développement, le fichier de log, la sortie SSR et test: 'log' hors du mode navigateur de Vitest. Elle n'est jamais envoyée au navigateur, donc elle ne masque ni la console du navigateur ni Vue DevTools : pour y masquer aussi une valeur, ajoutez une RegExp qui décrit sa forme. Un nombre correspond au littéral sous lequel il s'affiche ; une valeur vide ou non définie est ignorée, et toute autre valeur est ignorée avec un avertissement.

mtDebug({
  redact: [
    process.env.DB_PASSWORD ?? "", // chaîne : côté serveur uniquement
    /sk_live_[A-Za-z0-9]{8,}/, // RegExp : la forme d'un secret, masquée partout
    /(?<=x-api-key:\s*)\S+/, // une assertion arrière garde le nom de l'en-tête, masque la clé
  ],
});

Là où les entrées chaîne ne peuvent pas être lues, par exemple dans un SSR exécuté dans un processus à part, $debug n'y affiche rien plutôt que de les afficher en clair, et avertit une fois : voir Là où les entrées chaîne n'arrivent pas.

Dès qu'une entrée RegExp ou redactDefaults est configurée, les charges utiles, nœuds DOM compris, ne sont plus transmises comme objets vivants à la console du navigateur ni à la chronologie de Vue DevTools (pour un appel, { inspect: true } passe outre, pour la console seulement), et table() et dir() affichent le résumé masqué. Des entrées chaîne seules n'y changent rien : voir Valeurs vivantes dans le navigateur.

Le masquage est un filet de sécurité, pas un coffre-fort : il rattrape un secret qui atteint un appel $debug par erreur, et ne rend pas sûr le fait d'en loguer un. Voir Masquer les secrets.

`redactDefaults`

Type boolean. Valeur par défaut : false.

Applique aussi un jeu choisi de motifs de secrets : JWT, jetons Bearer, identifiants Basic après un en-tête Authorization:, adresses e-mail, clés de type Stripe, et les valeurs de clés secrètes comme password, token ou api_key, en propriétés d'objet ou en paires [key, value]. Comme une entrée RegExp, ils s'appliquent sur toutes les sorties. Les motifs utilisent des assertions arrière : Safari doit donc être en version 16.4 ou ultérieure pour exécuter votre page de développement. Voir Motifs par défaut.

`test`

Type false | 'stub' | 'log'. Valeur par défaut : 'stub'.

Ce que le plugin enregistre en tête de setupFiles sous Vitest :

'stub' installe un $debug inerte (nom de globale par défaut uniquement).
'log' installe un vrai journaliseur console qui tient compte de la configuration : les appels $debug(...) des composants et des fichiers de test s'affichent avec vos prefix, globalName, levels et prefixFilter, masqués par vos redact et redactDefaults. Chaque projet Vitest reçoit son propre journaliseur, construit à partir de sa propre configuration. Les entrées chaîne de redact n'atteignent pas toutes les configurations de Vitest : voir Entrées chaîne de redact dans les tests. Avec enabled: false, il retombe sur le bouchon.
false n'enregistre rien.

test remplace testStub et testLog. Les deux fonctionnent encore, avec un avertissement, jusqu'à la 2.0. Voir Tests.

Options du plugin​

Récapitulatif​

enabled​

levels​

minLevel​

output​

showSource​

prefix​

colors​

Fusion des surcharges de couleur​

globalName​

globalName personnalisé côté application​

prefixFilter​

filter​

showStack​

library​

redact​

redactDefaults​

test​