@sutsikinws/visual-debugger

v1.2.0

Published

10 days ago

A draggable visual debugger for Next.js applications with automatic network request capture

Downloads

460

0High
0Medium
0Low

sutsikinws

debug debugger visual nextjs react tailwind logging network

@sutsikinws/visual-debugger

Un debugger visuel draggable pour Next.js avec capture automatique des requêtes réseau.

✨ Fonctionnalités

🪟 Fenêtre draggable & resizable - Déplacez et redimensionnez la fenêtre comme sur Windows
🎨 Design minimaliste moderne - Interface épurée avec contrôles style macOS
🔝 Toujours au premier plan - Z-index ultra-élevé pour ne jamais perdre le debugger
📊 Niveaux de log multiples - log, info, warn, error
🔍 Recherche dans les logs - Filtrez vos logs avec une barre de recherche
🎯 Filtrage par niveau - Affichez uniquement les logs qui vous intéressent
🌐 Capture réseau automatique - Intercepte automatiquement fetch et XMLHttpRequest
⏱️ Timestamps lisibles - Format intelligent selon la date (HH:mm:ss.SSS)
📦 Objets structurés - Affichez des objets JSON avec formatage
🐛 Stack traces - Les erreurs affichent leur stack trace complète
🌙 Dark mode - Support automatique du dark mode via prefers-color-scheme
🚀 SSR safe - Compatible avec Next.js Server Components
👁️ Bouton intelligent - Se cache automatiquement quand la fenêtre est ouverte

📦 Installation

npm install @sutsikinws/visual-debugger

🚀 Quick Start

1. Ajouter le Debugger à votre Layout

Dans votre app/layout.tsx :

import { VisualDebugger } from '@sutsikinws/visual-debugger'
import './globals.css'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <VisualDebugger />
        {children}
      </body>
    </html>
  )
}

2. Utiliser l'API de Debug

Dans n'importe quel composant ou page :

'use client'

import { debug } from '@sutsikinws/visual-debugger'

export default function MyComponent() {
  const handleClick = () => {
    // Log simple
    debug.log('Button clicked!')

    // Log avec données
    debug.info('User action', { action: 'click', button: 'submit' })

    // Warning
    debug.warn('Deprecated API usage', { api: 'oldFunction()' })

    // Error
    debug.error(new Error('Something went wrong!'), { context: 'MyComponent' })
  }

  return <button onClick={handleClick}>Click me</button>
}

📚 API Reference

`debug.log(message, data?)`

Enregistre un message général.

debug.log('Simple message')
debug.log('User data', { userId: 123, name: 'John' })

`debug.info(message, data?)`

Enregistre un message d'information (badge bleu).

debug.info('Component mounted', { componentName: 'Header' })

`debug.warn(message, data?)`

Enregistre un avertissement (badge jaune).

debug.warn('Deprecated API', { api: 'oldMethod()' })

`debug.error(error, data?)`

Enregistre une erreur (badge rouge) avec stack trace.

debug.error(new Error('Failed to fetch'))
debug.error('Error message', { context: 'API call' })

`debug.clear()`

Efface tous les logs.

debug.clear()

🌐 Capture Réseau

Le debugger capture automatiquement toutes les requêtes réseau :

// Cette requête sera automatiquement loggée
const response = await fetch('https://api.example.com/data')

// Vous verrez dans le debugger :
// [FETCH] GET https://api.example.com/data
// - status: 200
// - duration: 245.32ms
// - response: { ... }

Supporte :

✅ fetch() API
✅ XMLHttpRequest
✅ Axios (utilise fetch/XHR sous le capot)

🎨 Interface Utilisateur

Bouton Toggle

Un bouton bleu en haut à droite de l'écran affiche :

Le nombre de logs (badge rouge)
Cliquez pour ouvrir/fermer la fenêtre

Fenêtre de Debug

La fenêtre contient :

Header : Titre, bouton Clear, bouton Close
Filtres : Boutons pour filtrer par niveau (LOG/INFO/WARN/ERROR)
Recherche : Barre de recherche en temps réel
Liste de logs : Défilement automatique vers le bas

Expansion des Logs

Cliquez sur la flèche à droite d'un log pour :

Voir les données structurées (JSON formaté)
Voir la stack trace (pour les erreurs)

⚙️ Configuration Avancée

Désactiver la Capture Réseau

Si vous ne voulez pas capturer les requêtes réseau, vous pouvez créer un wrapper :

// components/ConditionalDebugger.tsx
'use client'

import { VisualDebugger } from '@sutsikinws/visual-debugger'

export function ConditionalDebugger() {
  // Désactivez en production si nécessaire
  if (process.env.NODE_ENV === 'production') {
    return null
  }

  return <VisualDebugger />
}

Utiliser uniquement l'API de Log

Vous pouvez utiliser uniquement l'API sans afficher l'interface :

import { debug } from '@sutsikinws/visual-debugger'

// N'importez PAS <VisualDebugger />
// Utilisez seulement debug.log(), debug.info(), etc.

Les logs seront stockés en mémoire mais pas affichés.

🔧 Dépannage

Erreur "Module not found"

Problème : Cannot find module '@sutsikinws/visual-debugger'

Solution :

Vérifiez que le package est installé : npm list @sutsikinws/visual-debugger
Essayez de réinstaller : npm install @sutsikinws/visual-debugger
Redémarrez votre serveur de développement

Les requêtes réseau ne sont pas capturées

Problème : Les fetch ne s'affichent pas dans le debugger.

Solution :

Assurez-vous que <VisualDebugger /> est bien monté avant les requêtes
Vérifiez que vous n'avez pas d'autres interceptors qui entrent en conflit
Les requêtes côté serveur (Server Components) ne sont PAS capturées (par design)

Erreur d'hydration

Problème : Warning d'hydration dans la console.

Solution : Le composant utilise déjà useState avec mounted pour éviter ça. Si vous voyez toujours l'erreur, assurez-vous d'utiliser la dernière version du package.

📄 License

MIT © sutsiki

🤝 Contributing

Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou une pull request.

🐛 Report Bugs

Si vous trouvez un bug, créez une issue sur GitHub avec :

Description du problème
Steps pour reproduire
Version de Next.js
Version du package

📝 Changelog

1.2.0 (2026-01-05)

🎨 Removed Tailwind CSS dependency - Switched to standalone CSS for better compatibility and easier setup
⚡ No configuration required - CSS is automatically included with the component
🔧 Simplified installation - No need to configure Tailwind anymore
📦 Smaller bundle - Removed clsx dependency
🎯 Better styling reliability - Styles work out of the box regardless of consuming app's Tailwind configuration

1.1.1 (2026-01-05)

🐛 Fixed React Hooks error - Moved useCallback before conditional return to comply with Rules of Hooks

1.1.0 (2026-01-05)

🎨 Major UI redesign - Modern minimalist style with cleaner aesthetics
🪟 Resizable window - Resize from any edge or corner, like Windows Explorer
🎯 macOS-style controls - Beautiful traffic light buttons (red/yellow/green)
🔝 Higher z-index - Window now stays above everything (z-99998)
👁️ Smart toggle button - Automatically hides when window is open
⏱️ Better timestamps - More human-readable time format
🐛 Fixed drag & drop - Removed bounds restriction for smoother dragging
🎨 Updated colors - Using slate palette for modern look

1.0.1 (2026-01-05)

🐛 Fix React 19 compatibility - Added nodeRef to Draggable component to avoid findDOMNode deprecation error

1.0.0 (2026-01-05)

🎉 Initial release
✨ Fenêtre draggable
📊 Multiple log levels
🔍 Search & filters
🌐 Network interception
🎨 Dark mode support
🚀 SSR safe

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@sutsikinws/visual-debugger

✨ Fonctionnalités

📦 Installation

🚀 Quick Start

1. Ajouter le Debugger à votre Layout

2. Utiliser l'API de Debug

📚 API Reference

debug.log(message, data?)

debug.info(message, data?)

debug.warn(message, data?)

debug.error(error, data?)

debug.clear()

🌐 Capture Réseau

🎨 Interface Utilisateur

Bouton Toggle

Fenêtre de Debug

Expansion des Logs

⚙️ Configuration Avancée

Désactiver la Capture Réseau

Utiliser uniquement l'API de Log

🔧 Dépannage

Erreur "Module not found"

Les requêtes réseau ne sont pas capturées

Erreur d'hydration

📄 License

🤝 Contributing

🐛 Report Bugs

📝 Changelog

1.2.0 (2026-01-05)

1.1.1 (2026-01-05)

1.1.0 (2026-01-05)

1.0.1 (2026-01-05)

1.0.0 (2026-01-05)

`debug.log(message, data?)`

`debug.info(message, data?)`

`debug.warn(message, data?)`

`debug.error(error, data?)`

`debug.clear()`