MARS TECH vite-debug-plugin

Rendu côté serveur (SSR)

$debug est disponible dans le code rendu côté serveur : gardes de route, reducers de store, initialisation de page, middleware serveur. Le plugin installe la globale des deux côtés.

Environnements d'exécution navigateur et serveur

  • Navigateur : l'environnement d'exécution est injecté via transformIndexHtml. Il écrit dans console.{error|warn|info|debug|log|trace} et transmet chaque appel au terminal de développement par le WebSocket de Vite.
  • Serveur : un environnement d'exécution Node est injecté automatiquement dans chaque module transformé pour le SSR qui référence $debug, via le module virtuel virtual:mt-debug/ssr. Il écrit la sortie colorée ANSI directement sur process.stdout. En complément, pour les configurations SSR qui tournent dans le même processus, le plugin installe aussi $debug sur le globalThis du serveur de développement Vite depuis configureServer.

Le processus Vite et le code rendu côté serveur exécutent le même environnement d'exécution : un appel s'affiche donc de la même façon depuis un module SSR, depuis vite.config.ts ou depuis un autre plugin. output.terminal: false coupe aussi la sortie côté serveur, et $debug reste défini.

En production (vite build, y compris les builds SSR), chaque site d'appel est remplacé par void 0, quel que soit le côté. Aucun environnement d'exécution SSR n'est embarqué dans la sortie : voir Builds de production.

Activation SSR manuelle

Pour un rendu SSR exécuté dans un fil d'exécution séparé (worker thread) ou dans un processus séparé, qui ne partage pas globalThis avec Vite, importez le module virtuel depuis votre point d'entrée serveur :

ts
// par ex. src/main.server.ts (Analog) ou un plugin serveur Nuxt
import "virtual:mt-debug/ssr";

Le module peut être importé plusieurs fois sans risque : il installe $debug quand la globale est absente, remplace une instance antérieure de son propre environnement d'exécution (par exemple après un redémarrage de la configuration Vite), et n'écrase jamais un $debug défini par votre application. Il ne se charge qu'en développement : la suppression des appels en production retire toute référence à ce module. Il n'est servi qu'au traitement SSR : importé depuis du code client, c'est un module vide. Avec des entrées chaîne dans redact, un rendu exécuté dans son propre processus n'affiche rien : voir Entrées chaîne de redact côté serveur.

Les appels côté serveur arrivent aussi dans le fichier de log NDJSON quand l'environnement d'exécution SSR tourne dans le processus Vite ; un processus SSR séparé n'est pas vu. Voir Fichier de log NDJSON.

Entrées chaîne de redact côté serveur

Une entrée chaîne de redact, généralement un secret lu dans l'environnement, n'est jamais écrite dans l'environnement d'exécution SSR : chaque affichage la lit dans la mémoire du processus qui charge votre configuration. Elle atteint :

  • le SSR dans le processus Vite : ssrLoadModule, le module runner, vite-node ;
  • un fil d'exécution (worker thread) démarré après le plugin, comme le worker Nitro de Nuxt, y compris après un redémarrage dû à nuxt.config.

Le SSR dans un processus à part, ou dans workerd (@cloudflare/vite-plugin), ne peut pas la lire. $debug n'y affiche rien plutôt que d'afficher une ligne où vos entrées chaîne ne seraient pas masquées, et avertit une fois :

text
[MARS-TECH] $debug prints nothing in this process: the string entries of your redact option do not reach it, and it does not print what it cannot mask. […]

Pour y voir la sortie, décrivez chacune de ces valeurs par une RegExp de sa forme (/sk_live_[A-Za-z0-9]+/) au lieu d'une chaîne. Un fil d'exécution démarré avant la création du plugin est dans la même situation : redémarrez-le. Sans entrée chaîne, chaque environnement d'exécution affiche sa sortie, masquée par vos entrées RegExp et redactDefaults. Voir Là où les entrées chaîne n'arrivent pas.