DevBubble 🫧

🎉 CURRENT RELEASE - v0.2.0
Panel UI implemented! Complete logging interface with expandable panel. Ready for development use.

DevBubble is a development-only debugging overlay widget that displays logs, errors, and debug information in a beautiful, user-friendly interface during development.

🎯 Core Philosophy: DevBubble is a display layer - your application detects issues, DevBubble makes them beautiful and accessible.

✅ Current Status (v0.2.0)

✅ Logging API - error(), warn(), log(), clear(), getLogs()
✅ Visual feedback - Bubble changes color based on log severity
✅ Panel UI - Expandable interface for viewing detailed logs
✅ Smart storage - FIFO system with automatic cleanup
✅ TypeScript + ES/UMD builds - Full type safety
✅ Comprehensive tests - 50 tests covering all functionality

🚀 Current API (v0.2.0 - Available Now!)

Available Now

import { init, error, warn, log, clear, getLogs } from 'devbubble';

// Initialize DevBubble (call once)
init(); // Uses default position (bottom-right)
// or customize position
init({ position: 'top-left' }); // 'top-left', 'top-right', 'bottom-left', 'bottom-right'

// Simple usage
error('Email validation failed');
warn('Deprecated API used');
log('User logged in', { userId: 123 });

// With rich context
error('Database connection failed', {
  description: 'Could not connect after 3 retries',
  database: 'users',
  retryCount: 3
});

// Clear logs when needed
clear();

// Get all stored logs
const logs = getLogs(); // Returns LogEntry[]

Visual States & Panel

🔴 Red bubble - Errors present
🟡 Yellow bubble - Warnings (no errors)
🔵 Blue bubble - Info logs only
⚪ Gray bubble - No logs
📋 Click bubble - Opens expandable panel with detailed logs

🎯 Installation

npm install devbubble
# or
yarn add devbubble
# or
pnpm add devbubble

🚀 Quick Start

import { init, error, warn, log, clear, getLogs } from 'devbubble';

// Initialize once in your app
init();

// The bubble appears automatically when you log something
error('Email validation failed');
warn('Deprecated API used');
log('User logged in', { userId: 123 });

// Click the bubble to see detailed logs in the panel

🎨 Development

This project uses:

pnpm for package management
Vite for building and development
TypeScript for type safety
Storybook for component development

Setup

git clone https://github.com/nascjoao/devbubble
cd devbubble
pnpm install

Development Scripts

pnpm dev          # Start Vite development server
pnpm build        # Build library for production
pnpm test         # Run tests with coverage
pnpm test:run     # Run tests once
pnpm storybook    # Start Storybook development server

🎯 How It Works

import { init, error } from 'devbubble';

// 1. Initialize DevBubble once
init();

// 2. Your app detects a problem
if (!email.includes('@')) {
  
  // 3. Report to DevBubble with clear summary
  error('Email validation failed', { 
    description: 'Email must contain @ symbol',
    field: 'email',
    value: email,
    component: 'UserForm' 
  });
  
  // 4. DevBubble displays it visually
  // - Bubble appears and turns red to indicate errors
  // - Click bubble to see detailed logs in expandable panel
}

Responsibility split:

Your app: Detects issues, validates data, decides what to report
DevBubble: Receives, formats and displays information beautifully

📚 Documentation

Architecture - Core principles and design philosophy
Contributing - How to contribute to the project
API Reference - Detailed API documentation (planned for v0.2.0)

📖 Roadmap

Next Versions

v0.1.0: Basic widget + positioning (completed)
v0.2.0: Essential API (error(), warn(), log()) + panel UI + visual feedback (completed - current)
v0.3.0: Advanced filtering, search, and theme customization
v0.4.0: Performance optimization, advanced configuration
v1.0.0: Stable API + comprehensive documentation

Current Implementation Details (v0.2.0)

✅ FIFO storage with 100 log limit (automatic cleanup)
✅ Safe serialization (handles circular references)
✅ Visual severity indication (red/yellow/blue/gray states)
✅ Expandable panel interface with real-time updates
✅ Full TypeScript support with proper types

🤝 Contributing

This project is in active collaborative development! Please read our Contributing Guide to understand the project scope and development workflow.

Quick Start:

Read ARCHITECTURE.md to understand the design principles
Check the current issues
Fork, create a feature branch, and submit a PR

📄 License

MIT © nascjoao

Note: This library is designed for development environments. Make sure to disable it in production builds.