React Native Beautiful Logs 🌈✨

Tired of console.log clutter? react-native-beautiful-logs elevates your debugging experience with gorgeous, organized console output and robust file logging capabilities, all with a simple and intuitive API.

✨ Features

• 🎨 Eye-Catching Console Logs: Configurable ANSI colors, timestamps, log levels with emojis (🔍📱⚠️❌), and clear module tagging make reading logs a joy, not a chore.
• 🏷️ Module Tagging: Easily identify log origins using [ModuleName] prefixes (e.g., log('info', '[AuthService]', 'Login successful')).
• 🧠 Smart Formatting: Automatically pretty-prints Objects, Arrays, and Errors in the console and file logs for maximum readability.
• 💾 Persistent File Logging: Logs are automatically saved to platform-appropriate locations (Documents on iOS, Cache on Android).
• 🔄 Automatic File Management: Built-in log rotation and cleanup based on file count, age, and size limits. Set it and forget it!
• 🛠️ Robust & Resilient: Handles Android encoding fallbacks (UTF-8/Base64) and filesystem errors gracefully. Asynchronous operations ensure logging doesn't block your UI.
• 📂 File Management Interface: Programmatically access log files (getLogFiles, readLogFile, deleteLogFile, deleteAllLogs) via the loggerInterface.
• ⚙️ Configurable Filtering: Easily filter out noisy logs by defining substrings in the LOG_FILTERS constant.
• 🔒 Typed API: Written entirely in TypeScript for excellent developer experience and type safety.

🚀 Installation

# Using npm
npm install react-native-beautiful-logs react-native-blob-util

# Using yarn
yarn add react-native-beautiful-logs react-native-blob-util

iOS Setup

cd ios && pod install

Additional Setup

No additional setup required! The library will initialize automatically when imported.

💡 Basic Usage

import { log } from 'react-native-beautiful-logs';

// Simple logs (default level: info)
log('Hello world');
log('[MyComponent]', 'Component mounted');

// With specific log levels
log('debug', '[Network]', 'Request started', { url: '/api/users' });
log('info', '[Auth]', 'User logged in successfully');
log('warn', '[API]', 'Rate limit approaching');
log('error', '[Database]', 'Connection failed', new Error('Timeout'));

// Logging objects
const data = { id: 1, status: 'active' };
log('info', '[Data]', 'Current state:', data);

// Error handling
try {
  throw new Error('Operation failed');
} catch (error) {
  log('error', '[ErrorHandler]', 'Caught error:', error);
}

📁 Working with Log Files

import { loggerInterface } from 'react-native-beautiful-logs';

async function exportLogs() {
  // Get all log files (sorted by date, newest first)
  const files = await loggerInterface.getLogFiles();

  // Read current session's logs
  const currentLogs = await loggerInterface.getCurrentSessionLog();

  // Read a specific log file
  if (files.length > 0) {
    const oldLogs = await loggerInterface.readLogFile(files[0]);
  }

  // Clean up old logs
  await loggerInterface.deleteAllLogs();
}

📖 API Documentation

Core Functions

log(levelOrMessage: LogLevel | unknown, ...args: unknown[]): void

The primary function for logging.

• Level Handling:
  • If the first argument is a valid LogLevel ('debug', 'info', 'warn', 'error'), it's used as the level.
  • Otherwise, the level defaults to 'info', and the first argument is treated as part of the message.
• Module Tagging (Recommended): Include a tag like [MyComponent] or [MyService] as the first string argument (after the level, if provided) for easy identification in logs.
• Arguments (...args): Accepts any number of additional arguments (strings, numbers, booleans, objects, arrays, Errors, null, undefined). These are intelligently formatted for both console and file output.
• Console Output: Formatted with timestamp, level symbol/name, module tag, and colors. Objects/Errors are pretty-printed.
• File Output: Plain text format: YYYY-MM-DD HH:mm:ss.SSS [LEVEL] Message content.... Colors are stripped, objects/errors are stringified.

initSessionLog(): Promise<boolean>

Manually initializes the file logging session.

• Ensures the log directory exists (trying default and fallback locations).
• Creates or verifies the log file for the current 2-day window.
• Writes a session start marker to the file.
• Triggers log cleanup.
• Returns true on success, false on failure (errors logged internally).
• Note: Called automatically on the first log() if not called manually, but calling it early ensures predictability.

File Management

loggerInterface: LoggerInterface

An object providing methods to interact with log files.

• getLogFiles(): Promise<string[]>: Returns a sorted list (newest first) of available log filenames (e.g., ['session_2024-03-15.txt', ...]).
• getCurrentSessionLog(): Promise<string>: Reads the content of the currently active log file. Returns "" on error.
• readLogFile(filename: string): Promise<string | null>: Reads the content of a specific log file. Returns null if not found, empty, or on error. Handles Android Base64 decoding automatically.
• deleteLogFile(filename: string): Promise<boolean>: Deletes a specific log file. Cannot delete the active session log. Returns true on success or if file didn't exist.
• deleteAllLogs(): Promise<boolean>: Deletes all log files except the active one. Returns true if all deletions succeeded.
• cleanupCurrentSession(): Promise<void>: Resets internal session state and deletes the current log file only if it's empty.

(See types.ts or hover in your IDE for detailed JSDoc on LoggerInterface methods)

Types

import type { LogLevel, LoggerInterface, LoggerConfig } from 'react-native-beautiful-logs';

Use these imported types for strong typing when interacting with the library.

⚙️ Configuration (Via Constants)

Currently, configuration is managed by editing the constants directly in the library's source files before building your app. Runtime configuration is planned for the future.

Key constants in src/constants.ts:

• LOG_FILTERS: string[]: Array of substrings. Logs containing any of these (case-insensitive) will be skipped entirely.
  • Example: ['[Network]', 'Password'] filters network logs and any log containing "Password".
• MAX_LOG_FILES: number: Max number of log files to keep (default: 50). Oldest are deleted first.
• MAX_LOG_AGE_DAYS: number: Max age in days for log files (default: 30). Older files are deleted.
• MAX_LOG_SIZE_MB: number: Max size in MB per log file (default: 10). Triggers rollover check on next write.
• DEFAULT_LOG_DIR_BASE: string: Platform-specific default base directory (DocumentDir for iOS, CacheDir for Android).
• FALLBACK_DIRS: string[]: Directories to try if the default fails.
• LOGS_SUBDIR: string: Subdirectory name within the base dir (default: 'logs').
• SYMBOLS: Record<LogLevel, string>: Emojis used for log levels in console output.
• COLORS: Record<..., string>: ANSI color codes for console output styling.

📸 Output Previews

Console Output Example

14:05:10.345 📱 INFO  [Network] → Request successful: { status: 200, items: 42 }
14:05:11.802 🔍 DEBUG [DataStore] → Cache miss for key: user:101
14:05:12.100 ⚠️ WARN  [AuthService] → Token nearing expiration.
14:05:13.567 ❌ ERROR [PaymentFlow] → Payment processing failed:
│  Error: Insufficient funds
│    at processPayment (payment.js:152)
│    at checkout (checkout.js:88)

File Output Example (session_YYYY-MM-DD.txt)

=== New Log Session Started at 2024-03-15 14:05:09.123 ===
2024-03-15 14:05:10.345 [INFO] Request successful: { status: 200, items: 42 }
2024-03-15 14:05:11.802 [DEBUG] Cache miss for key: user:101
2024-03-15 14:05:12.100 [WARN] Token nearing expiration.
2024-03-15 14:05:13.567 [ERROR] Payment processing failed: Error: Insufficient funds
  at processPayment (payment.js:152)
  at checkout (checkout.js:88)
=== App Session Resumed at 2024-03-15 15:30:00.001 ===
2024-03-15 15:30:05.010 [INFO] App resumed from background.

🗄️ Storage Details

• 📱 iOS Default: <App Sandbox>/Documents/logs/session_YYYY-MM-DD.txt (Persistent, User Accessible via Files App, Backed Up)
• 🤖 Android Default: <App Sandbox>/cache/logs/session_YYYY-MM-DD.txt (App Specific Cache, May Be Cleared by OS/User)
• Note: Fallback directories might be used if defaults fail (see FALLBACK_DIRS in constants.ts).

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

⭐️ Show Your Support

Give a ⭐️ if this project helped you!

📄 License

Distributed under the MIT License. See LICENSE file for more information.

MIT © Rakshit Bharat