MARS TECH vite-debug-plugin

MARS TECH

@mars-tech/vite-debug-pluginUn $debug() global en développement, absent en production

Un plugin Vite libre, conçu par MARS TECH. Un seul appel s'affiche dans la console du navigateur et dans le terminal Vite, puis disparaît de la compilation de production, arguments compris.

  • Double sortie

    Chaque appel s'affiche dans la console du navigateur (avec mise en forme) et dans le terminal Vite (couleurs ANSI), avec une couleur par niveau, une étiquette et l'emplacement dans le code source.

    Comment ça marche

  • Inspection vive dans le navigateur

    Objets, instances de classe, nœuds DOM et piles d'appels des Error restent interactifs dans la console du navigateur, comme avec console.log.

    Inspection d'objets vivante

  • Vue DevTools

    Dans les applications Vue et Nuxt, chaque appel $debug apparaît aussi dans une couche de chronologie et un inspecteur MARS-TECH de Vue DevTools, avec sa charge utile et son emplacement source, dès que @vue/devtools-api est installé.

    Vue DevTools

  • Coût nul en production

    Chaque appel $debug(...), formes méthode et chaînée comprises, est remplacé par void 0 à la compilation, puis éliminé du code produit. Les expressions passées en argument ne sont jamais évaluées.

    Compilation de production

  • Prêt pour le rendu serveur

    La globale est aussi installée côté serveur : gardes du routeur, actions de gestion d'état et initialisation des pages peuvent journaliser pendant le rendu côté serveur (SSR).

    Rendu côté serveur

  • Espaces de noms et filtrage à l'exécution

    Journaux par espace de noms avec $debug.ns('auth'). Choisissez ce qui s'affiche à l'exécution avec enable, disable ou setLevel, le paramètre d'URL ?mt-debug=, localStorage ou la variable MT_DEBUG, sans redémarrage.

    Espaces de noms et filtrage

  • Masquage des secrets

    Un filet de sécurité pour un secret glissé dans un log : masquez les jetons, les adresses électroniques et vos propres motifs. Un motif qui décrit la forme d'un secret masque aussi la console du navigateur ; une valeur listée comme chaîne est masquée côté serveur et n'est jamais envoyée à la page.

    Masquer les secrets

  • Fonctions utilitaires

    Des fonctions inspirées de console : assert, time/timeEnd, count, group/groupEnd, table et dir, retirées de la compilation de production comme les appels de base.

    Fonctions utilitaires

  • Création de bibliothèque

    library.debugBuild produit une double variante : votre bibliothèque journalise en développement et ses appels sont retirés de la compilation de production.

    Création de bibliothèque

  • TypeScript et ESLint intégrés

    Les types globaux sont livrés dans /client pour tous les modes de résolution de modules, et /eslint fournit une configuration plate qui déclare la globale $debug.

    Démarrage rapide

Installation

sh
npm install -D @mars-tech/vite-debug-plugin
sh
pnpm add -D @mars-tech/vite-debug-plugin
sh
yarn add -D @mars-tech/vite-debug-plugin

Enregistrez ensuite le plugin dans vite.config.ts :

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

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

Enregistrez-le sans condition, dans le tableau plugins de premier niveau : pendant vite build, c'est le plugin qui supprime les appels $debug. Le démarrage rapide ajoute le typage de la globale et la configuration ESLint.

Comment ça marche

La démonstration ci-dessous suit une application Vue sur trois pages. Chaque ligne commence par MARS-TECH, le préfixe par défaut de ce plugin MARS TECH ; l'option prefix le remplace par le vôtre.

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 emplacement dans le code source.

localhost:4312/
Application Vue de démonstration, page d’accueil après défilement : la fin d’une carte de test de Vue DevTools avec un bouton par type de charge utile, 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 (src/main.ts:7:0)
MARS-TECH Trace [component/App] - App.vue setup (src/App.vue:4:0)
MARS-TECH Trace [router/beforeEach] - nav: / → / (src/router/index.ts:25:2)
MARS-TECH Trace [shell/mounted] - PageShell mounted (src/components/PageShell.vue:10:2)
MARS-TECH Info [SomeButton/mounted] - SomeButton mounted with variant=primary (src/components/SomeButton.vue:26:4)
MARS-TECH Trace [shell/mounted] - PageShell mounted (src/components/PageShell.vue:10:2)
MARS-TECH Trace [shell/mounted] - PageShell mounted (src/components/PageShell.vue:10:2)
MARS-TECH Success [view/Home] - Home mounted (src/views/Home.vue:16:2)
MARS-TECH Info [store/counter] - counter incremented to 1 (src/stores/counter.ts:8:6)
MARS-TECH Info [store/counter] - counter incremented to 2 (src/stores/counter.ts:8:6)

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, et chaque ligne indique le fichier, la ligne et la colonne de l’appel.

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 (src/router/index.ts:25:2)
MARS-TECH Trace [view/About/lifecycle] - About created (src/views/About.vue:27:4)
MARS-TECH Trace [shell/mounted] - PageShell mounted (src/components/PageShell.vue:10:2)
MARS-TECH Success [view/About/lifecycle] - About mounted (src/views/About.vue:30:4)
MARS-TECH Info [view/About/method] - delayed fire #1 (src/views/About.vue:40:8)
MARS-TECH Debug [view/About/watch] - delayedCount: 0 → 1 (src/views/About.vue:21:6)

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 (src/router/index.ts:25:2)
MARS-TECH Warning [view/About/lifecycle] - About beforeUnmount (src/views/About.vue:33:4)
MARS-TECH Trace [shell/mounted] - PageShell mounted (src/components/PageShell.vue:10:2)
MARS-TECH Trace [view/Sandbox] - Sandbox mounted (src/views/Sandbox.vue:10:2)
MARS-TECH Error [view/Sandbox/handler] - inline throw inside Sandbox handler (src/views/Sandbox.vue:26:4)
  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=7dcb8c1b:1889:17)
      at callWithAsyncErrorHandling (http://localhost:4312/node_modules/.vite/deps/vue.runtime.esm-bundler-BbnC8aGa.js?v=7dcb8c1b:1896:15)
      at HTMLButtonElement.invoker (http://localhost:4312/node_modules/.vite/deps/vue.runtime.esm-bundler-BbnC8aGa.js?v=7dcb8c1b: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 emplacement dans le code source.

    Sortie :

    $ npm run dev -- --port 4312 --strictPort
MARS-TECH Info [main] - bootstrapping Vue app (src/main.ts:7:0)
MARS-TECH Trace [component/App] - App.vue setup (src/App.vue:4:0)
MARS-TECH Trace [router/beforeEach] - nav: / → / (src/router/index.ts:25:2)
MARS-TECH Trace [shell/mounted] - PageShell mounted (src/components/PageShell.vue:10:2)
MARS-TECH Info [SomeButton/mounted] - SomeButton mounted with variant=primary (src/components/SomeButton.vue:26:4)
MARS-TECH Trace [shell/mounted] - PageShell mounted (src/components/PageShell.vue:10:2)
MARS-TECH Trace [shell/mounted] - PageShell mounted (src/components/PageShell.vue:10:2)
MARS-TECH Success [view/Home] - Home mounted (src/views/Home.vue:16:2)
MARS-TECH Info [store/counter] - counter incremented to 1 (src/stores/counter.ts:8:6)
MARS-TECH Info [store/counter] - counter incremented to 2 (src/stores/counter.ts:8:6)

  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, et chaque ligne indique le fichier, la ligne et la colonne de l’appel.

    Sortie :

    MARS-TECH Trace [router/beforeEach] - nav: / → /about (src/router/index.ts:25:2)
MARS-TECH Trace [view/About/lifecycle] - About created (src/views/About.vue:27:4)
MARS-TECH Trace [shell/mounted] - PageShell mounted (src/components/PageShell.vue:10:2)
MARS-TECH Success [view/About/lifecycle] - About mounted (src/views/About.vue:30:4)
MARS-TECH Info [view/About/method] - delayed fire #1 (src/views/About.vue:40:8)
MARS-TECH Debug [view/About/watch] - delayedCount: 0 → 1 (src/views/About.vue:21:6)

  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 (src/router/index.ts:25:2)
MARS-TECH Warning [view/About/lifecycle] - About beforeUnmount (src/views/About.vue:33:4)
MARS-TECH Trace [shell/mounted] - PageShell mounted (src/components/PageShell.vue:10:2)
MARS-TECH Trace [view/Sandbox] - Sandbox mounted (src/views/Sandbox.vue:10:2)
MARS-TECH Error [view/Sandbox/handler] - inline throw inside Sandbox handler (src/views/Sandbox.vue:26:4)
  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=7dcb8c1b:1889:17)
      at callWithAsyncErrorHandling (http://localhost:4312/node_modules/.vite/deps/vue.runtime.esm-bundler-BbnC8aGa.js?v=7dcb8c1b:1896:15)
      at HTMLButtonElement.invoker (http://localhost:4312/node_modules/.vite/deps/vue.runtime.esm-bundler-BbnC8aGa.js?v=7dcb8c1b:7677:10)

Le guide « Comment ça marche » reprend ces étapes et explique ce que devient chaque appel dans la compilation de production.