MARS TECH vite-debug-plugin

Vous lisez la documentation de la version 0.6, qui n'est pas la dernière publiée.

Lire cette page dans la documentation la plus récente (v1.0)

Comment ça marche

@mars-tech/vite-debug-plugin est un plugin Vite qui expose une fonction globale $debug en développement. Chaque appel s'affiche simultanément dans la console du navigateur et dans le terminal du serveur de développement Vite, avec un formatage et des couleurs cohérents par niveau de sévérité. Tous les appels à $debug sont supprimés des builds de production, y compris leurs expressions d'arguments.

Fonctionne avec n'importe quel framework basé sur Vite : Vue 3.5, React, Angular (via Analog), Nuxt 4, SvelteKit, Astro server, Vite SSR, etc. Le code côté client et le code rendu côté serveur (SSR) sont pris en charge. Consultez les recettes par framework pour les sites d'appel propres à chaque pile, et Rendu côté serveur (SSR) pour le côté serveur.

Le plugin en action

Chaque ligne commence par MARS-TECH, le préfixe par défaut. Modifiez-le avec l'option prefix.

Fonctionnement du plugin en 3 étapes : les mêmes appels $debug() affichés dans la console du navigateur et dans le terminal Vite.

Lancer le serveur de développement. Lancez le serveur de développement, ouvrez l’application et cliquez deux fois sur +1. Chaque appel à $debug, d’abord au démarrage de l’application puis dans l’action du store Pinia, affiche la même ligne dans la console du navigateur et dans le terminal Vite : niveau, étiquette, message et un emplacement source. En 0.6, un appel fait dans le navigateur indique comme emplacement le module d’exécution du plugin lui-même au lieu de l’endroit de l’appel ; la version 1.0 corrige ce défaut.

localhost:4312/
Application Vue de démonstration, page d’accueil : l’en-tête et ses trois liens de navigation, un bandeau invitant à ouvrir la console du navigateur et le terminal Vite, puis la carte du compteur Pinia, qui affiche 2 après deux clics sur +1.
Console du navigateur
Terminal — vite dev
$ npm run dev -- --port 4312 --strictPort
MARS-TECH Info [main] - bootstrapping Vue app (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [component/App] - App.vue setup (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [router/beforeEach] - nav: / → / (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [shell/mounted] - PageShell mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Info [SomeButton/mounted] - SomeButton mounted with variant=primary (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [shell/mounted] - PageShell mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [shell/mounted] - PageShell mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Success [view/Home] - Home mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Info [store/counter] - counter incremented to 1 (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Info [store/counter] - counter incremented to 2 (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)

Naviguer vers une autre page. Ouvrez la page About et cliquez sur Fire delayed (500 ms). Les hooks de cycle de vie, une méthode appelée après un minuteur et un observateur journalisent tous via $debug.

localhost:4312/about
Application Vue de démonstration, page À propos : une carte de démonstration de l’API Options qui liste les étapes du cycle de vie, un observateur, une méthode asynchrone et un libellé calculé ; après un clic sur le bouton de déclenchement différé (500 ms), l’état indique un déclenchement.
Console du navigateur
Terminal — vite dev
MARS-TECH Trace [router/beforeEach] - nav: / → /about (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [view/About/lifecycle] - About created (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [shell/mounted] - PageShell mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Success [view/About/lifecycle] - About mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Info [view/About/method] - delayed fire #1 (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Debug [view/About/watch] - delayedCount: 0 → 1 (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)

Provoquer une erreur. Ouvrez la page Sandbox et cliquez sur Throw + log. Quitter la page About journalise son avertissement beforeUnmount, et l’erreur interceptée est journalisée avec sa pile d’appels.

localhost:4312/sandbox
Application Vue de démonstration, page Bac à sable : une carte sur le routeur et les chemins d’erreur, avec un bouton qui lève et journalise une erreur et un bouton de navigation vers /missing ; dessous, le message de la dernière erreur interceptée.
Console du navigateur
Terminal — vite dev
MARS-TECH Trace [router/beforeEach] - nav: /about → /sandbox (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Warning [view/About/lifecycle] - About beforeUnmount (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [shell/mounted] - PageShell mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [view/Sandbox] - Sandbox mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Error [view/Sandbox/handler] - inline throw inside Sandbox handler (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
  Error: inline throw inside Sandbox handler
      at throwInline (http://localhost:4312/src/views/Sandbox.vue:38:11)
      at callWithErrorHandling (http://localhost:4312/node_modules/.vite/deps/vue.runtime.esm-bundler-BbnC8aGa.js?v=ad0296fb:1889:17)
      at callWithAsyncErrorHandling (http://localhost:4312/node_modules/.vite/deps/vue.runtime.esm-bundler-BbnC8aGa.js?v=ad0296fb:1896:15)
      at HTMLButtonElement.invoker (http://localhost:4312/node_modules/.vite/deps/vue.runtime.esm-bundler-BbnC8aGa.js?v=ad0296fb:7677:10)
Version texte de cette animation

La console du navigateur et le terminal Vite affichent les mêmes lignes. Dans le navigateur, le niveau est coloré et l’emplacement source est en italique ; dans le terminal, l’emplacement source est grisé. Une pile d’appels suit sa ligne dans le terminal et se trouve dans un groupe « stack » replié dans la console.

  1. Étape 1 sur 3 — Lancer le serveur de développement. Lancez le serveur de développement, ouvrez l’application et cliquez deux fois sur +1. Chaque appel à $debug, d’abord au démarrage de l’application puis dans l’action du store Pinia, affiche la même ligne dans la console du navigateur et dans le terminal Vite : niveau, étiquette, message et un emplacement source. En 0.6, un appel fait dans le navigateur indique comme emplacement le module d’exécution du plugin lui-même au lieu de l’endroit de l’appel ; la version 1.0 corrige ce défaut.

    Sortie :

    $ npm run dev -- --port 4312 --strictPort
MARS-TECH Info [main] - bootstrapping Vue app (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [component/App] - App.vue setup (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [router/beforeEach] - nav: / → / (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [shell/mounted] - PageShell mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Info [SomeButton/mounted] - SomeButton mounted with variant=primary (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [shell/mounted] - PageShell mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [shell/mounted] - PageShell mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Success [view/Home] - Home mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Info [store/counter] - counter incremented to 1 (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Info [store/counter] - counter incremented to 2 (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)

  2. Étape 2 sur 3 — Naviguer vers une autre page. Ouvrez la page About et cliquez sur Fire delayed (500 ms). Les hooks de cycle de vie, une méthode appelée après un minuteur et un observateur journalisent tous via $debug.

    Sortie :

    MARS-TECH Trace [router/beforeEach] - nav: / → /about (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [view/About/lifecycle] - About created (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [shell/mounted] - PageShell mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Success [view/About/lifecycle] - About mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Info [view/About/method] - delayed fire #1 (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Debug [view/About/watch] - delayedCount: 0 → 1 (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)

  3. Étape 3 sur 3 — Provoquer une erreur. Ouvrez la page Sandbox et cliquez sur Throw + log. Quitter la page About journalise son avertissement beforeUnmount, et l’erreur interceptée est journalisée avec sa pile d’appels.

    Sortie :

    MARS-TECH Trace [router/beforeEach] - nav: /about → /sandbox (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Warning [view/About/lifecycle] - About beforeUnmount (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [shell/mounted] - PageShell mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Trace [view/Sandbox] - Sandbox mounted (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
MARS-TECH Error [view/Sandbox/handler] - inline throw inside Sandbox handler (http://localhost:4312/@mars-tech-vite-debug/runtime:201:3)
  Error: inline throw inside Sandbox handler
      at throwInline (http://localhost:4312/src/views/Sandbox.vue:38:11)
      at callWithErrorHandling (http://localhost:4312/node_modules/.vite/deps/vue.runtime.esm-bundler-BbnC8aGa.js?v=ad0296fb:1889:17)
      at callWithAsyncErrorHandling (http://localhost:4312/node_modules/.vite/deps/vue.runtime.esm-bundler-BbnC8aGa.js?v=ad0296fb:1896:15)
      at HTMLButtonElement.invoker (http://localhost:4312/node_modules/.vite/deps/vue.runtime.esm-bundler-BbnC8aGa.js?v=ad0296fb:7677:10)

Comportement en production

En vite build (client et SSR), chaque appel à l'identifiant global configuré (par défaut $debug, réglé par l'option globalName) est remplacé par void 0. Les expressions d'arguments ne sont pas évaluées.

ts
// avant
$debug("debug", expensiveCompute());

// après build
void 0;

Vous pouvez donc placer un coût d'exécution dans les arguments sans craindre d'impact en production — et aucun environnement d'exécution SSR n'est embarqué.

Les formes méthode et chaînée sont retirées aussi : $debug.time(...) → void 0, et un $debug.ns('x')('info') écrit en ligne est réduit à void 0 (la chaîne entière, donc jamais de void 0(...)). Une fabrique de journaliseur à espace de noms ($debug.ns('x')) est remplacée par une fonction vide appelable (() => {}) plutôt que void 0 : un journaliseur stocké dans une variable (const log = $debug.ns('x')) reste sûr à appeler après la suppression — et la fonction vide disparaît ensuite lors de l'élimination du code mort.

Vous publiez une bibliothèque qui appelle $debug ? Consultez Création de bibliothèque : allowDebugBuild produit une variante nettoyée et une variante de débogage dans le même build.