react-log-window

A lightweight, customizable logging window for React applications that provides user-facing logs. This library helps you display application events, errors, and information to your users in a clean, filterable interface.

Features

• 📋 Display user-facing logs in a clean, filterable interface
• 🎨 Light, dark, and auto themes
• 🔍 Filter logs by severity level (debug, info, warn, error)
• 📱 Responsive design with customizable dimensions
• 🖱️ Optional draggable and resizable window
• 📥 Download logs as text files
• 🔄 Auto-scrolling with smart pause/resume
• 🧩 Works both inside and outside React components
• 🌐 Global singleton logger - use anywhere without providers
• 🎭 Fully customizable with CSS

Installation

npm install react-log-window
# or
yarn add react-log-window

Basic Usage

Option 1: Quick Start (No Provider Required)

You can start logging immediately without setting up a provider:

import React from 'react';
import { logger, LogWindow } from 'react-log-window';

function App() {
  // Log directly using the global logger
  const handleClick = () => {
    logger.info("Button clicked");
  };
  
  return (
    <div className="app">
      <button onClick={handleClick}>Log Something</button>
      
      {/* Display logs */}
      <LogWindow />
    </div>
  );
}

Option 2: With Provider (Recommended for Component-Specific Control)

import React from 'react';
import { LoggerProvider, useLogger, LogWindow } from 'react-log-window';

function App() {
  return (
    <LoggerProvider maxEntries={500}>
      <YourApp />
      <LogWindow />
    </LoggerProvider>
  );
}

function YourApp() {
  const logger = useLogger();
  
  const handleAction = () => {
    logger.info("Action performed");
  };
  
  return (
    <div>
      <button onClick={handleAction}>Perform Action</button>
    </div>
  );
}

Logging from Components

import React from 'react';
import { useLogger } from 'react-log-window';

function UserDashboard() {
  const logger = useLogger();
  
  const handleAction = () => {
    logger.info("User initiated action");
    
    try {
      // Do something
      logger.debug("Action details", { id: 123, type: "update" });
      
      // Success
      logger.info("Action completed successfully");
    } catch (error) {
      logger.error("Action failed", error);
    }
  };
  
  return (
    <div>
      <button onClick={handleAction}>Perform Action</button>
    </div>
  );
}

Logging Outside React Components

import { logger } from 'react-log-window';

// In a utility function or service
function apiService() {
  logger.info("API service initialized");
  
  return {
    makeRequest: (url) => {
      logger.debug(`Making request to ${url}`);
      // Request logic
    }
  };
}

Advanced Usage

Floating, Draggable Log Window without controls and timestamps

<LogWindow 
  overlay={true}
  draggable={true}
  resizable={true}
  height={400}
  width={600}
  showControls={false}
  showTimestamp={false}
  theme="auto"
  defaultFilter={['warn', 'error']}
/>

Provider vs. No Provider

The library allows you to:

• Use without Provider: Logs are stored in a global singleton accessible everywhere
• Use with Provider: Logs are stored in the given context. Note that the provider will also access and display the global singleton logs.

The useLogger() hook automatically falls back to the global logger when used outside a provider.

Customizing the LoggerProvider

<LoggerProvider maxEntries={1000}>
  <YourApp />
</LoggerProvider>

Downloading Logs Programmatically

function DebugPanel() {
  const logger = useLogger();
  
  return (
    <div>
      <button onClick={() => logger.download("application-logs.txt")}>
        Download Logs
      </button>
      <button onClick={() => logger.clear()}>
        Clear Logs
      </button>
    </div>
  );
}

Subscribing to Log Changes

useEffect(() => {
  const unsubscribe = logger.subscribe((logs) => {
    // Do something with updated logs
    console.log(`Log count: ${logs.length}`);
  });
  
  return () => unsubscribe();
}, []);

Styling and Customization

The library uses standard CSS classes that you can override for complete visual customization.

CSS Classes

| Component | CSS Classes | |-----------|-------------| | Main Container | .log-window, .log-window-overlay, .log-window-theme-light, .log-window-theme-dark | | Header | .log-window-header, .log-window-title | | Controls | .log-window-controls, .log-window-filters, .log-window-actions | | Filter Buttons | .log-window-filter-btn, .log-window-level-debug, .log-window-level-info, .log-window-level-warn, .log-window-level-error | | Action Buttons | .log-window-action-btn | | Content | .log-window-content, .log-window-empty | | Log Entry | .log-window-entry, .log-window-timestamp, .log-window-level, .log-window-data | | Auto-scroll | .log-window-auto-scroll-active, .log-window-auto-scroll-btn | | Resize Handle | .log-window-resize-handle |

See components.css for the default styling.

Custom Styling Example

/* Custom dark theme */
.log-window-theme-dark {
  background-color: #1a1a1a;
  color: #e0e0e0;
  border: 1px solid #333;
}

/* Custom styling for error logs */
.log-window-level-error {
  background-color: rgba(255, 0, 0, 0.1);
  border-left: 4px solid #ff3333;
}

/* Custom header */
.log-window-header {
  background-color: #2a2a2a;
  padding: 8px 12px;
}

/* Custom scrollbar */
.log-window-content::-webkit-scrollbar {
  width: 8px;
}

.log-window-content::-webkit-scrollbar-thumb {
  background-color: #555;
  border-radius: 4px;
}

Adding Custom Classes

You can also add your own classes using the className prop:

<LogWindow 
  className="my-custom-log-window"
  height={300}
/>

API Reference

LoggerProvider Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | maxEntries | number | 1000 | Maximum number of log entries to retain | | children | ReactNode | | Child components |

LogWindow Props

| Prop | Type | Default | Description | |------|------|------------------------------------|-------------| | theme | 'light' | 'dark' | 'auto' | 'auto' | Visual theme | | height | number | string | 300 | Height of the log window | | width | number | string | '100%' | Width of the log window | | overlay | boolean | false | Whether to display as floating overlay | | draggable | boolean | false | Whether window can be moved (requires overlay) | | resizable | boolean | false | Whether window can be resized | | maxEntries | number | 1000 | Maximum number of entries to display | | defaultFilter | LogLevel[] | ['debug', 'info', 'warn', 'error'] | Default log levels to display | | showTimestamp | boolean | true | Whether to show timestamps | | showControls | boolean | true | Whether to show filter and action controls | | className | string | '' | Additional CSS class names |

Logger Methods

| Method | Parameters | Description | |--------|------------|-------------| | debug | (message: string, data?: any) | Log debug message | | info | (message: string, data?: any) | Log info message | | warn | (message: string, data?: any) | Log warning message | | error | (message: string, data?: any) | Log error message | | clear | () | Clear all logs | | download | (filename?: string) | Download logs as text file | | subscribe | (callback: (logs: LogEntry[]) => void) | Subscribe to log changes |

Use Cases

This library was created specifically with the thought of showing the actual user what is going in the background. It was never intended to provide insight to the developer and thus does not offer an option to send the logs to a remote server.

However, in cases of small applications where remote logs might be an overkill or are not desired, this could also prove useful for developing and debugging.

The focus is on improving the user experience through transparency, not on developer-focused logging or telemetry.

License

MIT