Démarrage rapide

Prérequis

Pile technique	Versions testées
Vite	6.x · 7.x · 8.x
Node.js	20.19 · 22.12 · 24 (24 recommandée ; la 20 a passé sa fin de vie)
Vue	3.5+ (Composition + Options API, Pinia, Vue Router)
React	18+ (Redux Toolkit, React Router)
Angular	20+ via Analog (NgRx, Angular Router)
Nuxt	4.x (Pinia, route middleware)
Moteurs SSR	Vite SSR, Analog, Nitro/Nuxt, vite-node

Voir Recettes par framework pour savoir où enregistrer le plugin dans chaque pile technique, avec un exemple de site d'appel idiomatique.

1. Installer et enregistrer le plugin

npm install -D @mars-tech/vite-debug-plugin

Enregistrez-le dans vite.config.ts :

// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import mtDebug from "@mars-tech/vite-debug-plugin";

export default defineConfig({
  plugins: [vue(), mtDebug()],
});

L'export par défaut est la fabrique du plugin. Elle fonctionne à l'identique avec import (ESM) et require() (CommonJS). Elle ne prend aucun argument par défaut : tous les réglages sont dans Options du plugin.

Enregistrez mtDebug() sans condition

Gardez-le dans le tableau plugins de premier niveau. Le plugin n'est pas qu'un outil de développement : pendant vite build, c'est lui qui supprime les appels à $debug. Ne le conditionnez pas à la commande ou au mode (command === "serve" && mtDebug()) et ne définissez pas apply: "serve" : le build livrerait alors chaque appel tel quel, et chacun lèverait une erreur en production. Pour couper l'environnement d'exécution de développement, utilisez enabled: false, qui supprime toujours les appels. Sous build.rollupOptions.plugins, ou dans une config Rollup ou Rolldown, le plugin ne fait que supprimer les appels et n'installe aucun environnement d'exécution.

2. Activer le typage de la globale $debug

Ajoutez une référence triple-slash là où vivent les types ambiants de votre projet (typiquement src/vite-env.d.ts) :

/// <reference types="@mars-tech/vite-debug-plugin/client" />

Résolution de modules

La résolution de modules doit lire la table exports du paquet (moduleResolution: "bundler", "node16" ou "nodenext"). Avec les modes hérités "node10" / "classic", le paquet livre aussi un client.d.ts à la racine qui se résout par chemin : rien à changer.

3. Déclarer la globale à ESLint

TypeScript connaît désormais $debug, mais la règle no-undef d'ESLint ne lit pas les types TS : elle signalera '$debug' is not defined. Étalez la configuration plate livrée pour déclarer la globale :

// eslint.config.js (config plate, ESLint 9 & 10)
import mtDebug from "@mars-tech/vite-debug-plugin/eslint";

export default [
  mtDebug, // déclare $debug en globale readonly
  // ...vos autres configs
];

L'export /eslint n'embarque aucune dépendance eslint, il ne fige donc jamais votre version : le même import fonctionne sur ESLint 9 et 10.

Votre configuration	Import
Configuration plate (ESLint 9 & 10)	l'export par défaut, étalé comme ci-dessus
globalName personnalisé	mtDebugFlatConfig({ globalName: "$log" })
.eslintrc (ESLint ≤9 seulement)	{ globals: mtDebugGlobals() } (le système eslintrc a été supprimé en v10)

Projets TypeScript

Les projets TypeScript peuvent aussi désactiver no-undef pour les fichiers .ts : tsc détecte déjà les noms non définis.

4. Appeler $debug dans le code de développement

$debug("warning", new Error('Invalid variant "danger"'), {
  tag: "PropsValidator",
});

Sortie (à la fois dans la console du navigateur et dans le terminal Vite) :

MARS-TECH Warning [PropsValidator] - Invalid variant "danger" (src/components/MyButton.vue:12:6)

MARS-TECH est le préfixe par défaut, Warning le libellé du niveau, PropsValidator l'étiquette (tag), et (fichier:ligne:colonne) en fin de ligne est l'emplacement d'origine de l'appel (désactivable avec showSource: false). Voir l'API $debug pour toutes les formes d'appel, et Comment ça marche pour une démonstration pas à pas.