@ru-dr/plip v1.1.0

🫧 Plip Logger

A delightful, colorful logging experience for modern Node.js applications

Installation • Quick Start • Documentation • Examples • Contributing

✨ Why Plip?

Tired of boring console logs? Plip brings joy back to logging with:

• 🌈 Smart Colors - Automatic terminal detection with beautiful color schemes
• 😊 Expressive Emojis - Visual context that makes logs easier to scan
• 🎯 7 Log Levels - From verbose to error, perfect granularity
• 🔍 Syntax Highlighting - JSON objects rendered beautifully
• ⚙️ Fluent API - Chain methods for elegant configuration
• 🚀 Zero Config - Works great out of the box, CSR by default
• 🌐 SSR/CSR Optimized - Specialized configs for server and client environments
• 📦 TypeScript First - Full type safety and IntelliSense
• 🔧 Environment Aware - Respects NODE_ENV and terminal capabilities

📦 Installation

::: code-group

$ npm install @ru-dr/plip

$ yarn add @ru-dr/plip

$ pnpm add @ru-dr/plip

$ bun add @ru-dr/plip

:::

🌍 Multi-Language Support Coming Soon!
Plip is currently available for JavaScript/TypeScript environments. We're actively working on bringing the same delightful logging experience to Python, Java, PHP, and other popular languages. Follow our progress or contribute to help us expand faster!

🚀 Quick Start

Get logging in seconds:

import { plip } from '@ru-dr/plip';

plip.info("🎉 Welcome to Plip!");
plip.success("✅ Everything is working perfectly");
plip.warn("⚠️  This might need your attention");
plip.error("💥 Something went wrong");

// Log complex objects with beautiful syntax highlighting
plip.info("User profile:", {
  name: "Alex Developer",
  age: 28,
  skills: ["TypeScript", "Node.js", "React"],
  active: true
});

Output Preview:

🫧 [INFO] 🎉 Welcome to Plip!
🎉 [SUCCESS] ✅ Everything is working perfectly
⚠️ [WARN] ⚠️  This might need your attention
💥 [ERROR] 💥 Something went wrong
🫧 [INFO] User profile: {
  "name": "Alex Developer",
  "age": 28,
  "skills": ["TypeScript", "Node.js", "React"],
  "active": true
}

📚 API Documentation

Creating Logger Instances

import { plip, createPlip } from '@ru-dr/plip';

// Use the default logger (recommended for most cases)
plip.info("Using default logger");

// Create a custom logger with specific configuration
const customLogger = createPlip({
  enableEmojis: true,
  enableColors: true,
  enabledLevels: ['info', 'warn', 'error']
});

// Create a production logger
const prodLogger = createPlip({
  enableEmojis: false,
  enableColors: false,
  enabledLevels: ['warn', 'error']
});

🎨 Log Levels

Plip provides 7 distinct log levels, each with its own emoji and color:

// Using all log levels
plip.info("Application started successfully");
plip.success("User authenticated");
plip.warn("API rate limit approaching");
plip.error("Database connection failed");
plip.debug("Processing user request", { userId: 123 });
plip.trace("Function execution time: 45ms");
plip.verbose("System memory usage:", process.memoryUsage());

⚙️ Configuration Options

Customize Plip to fit your needs:

const logger = createPlip({
  silent: false,
  enableEmojis: true,
  enableColors: true,
  enableSyntaxHighlighting: true,
  devOnly: false,
  enabledLevels: ['info', 'warn', 'error', 'success'],
  theme: {
    emojis: {
      info: "ℹ️",
      success: "✅"
    },
    colors: {
      info: customBlueColor,
      success: customGreenColor
    }
  }
});

🔗 Fluent API (Method Chaining)

Build your perfect logger with our fluent, chainable API:

const logger = plip
  .withColors(true)           // Enable colors
  .withEmojis(true)           // Enable emojis
  .withSyntaxHighlighting(true) // Enable JSON highlighting
  .levels('info', 'error', 'success') // Only these levels
  .silent();                  // Make it silent

// Each method returns a new logger instance
const devLogger = plip.levels('debug', 'trace', 'verbose');
const prodLogger = plip.levels('warn', 'error').withEmojis(false);

Available Fluent Methods:

• .withColors(enabled) - Toggle color output
• .withEmojis(enabled) - Toggle emoji indicators
• .withSyntaxHighlighting(enabled) - Toggle object highlighting
• .withTheme(theme) - Apply custom theme
• .withContext(context) - Add persistent context to all logs
• .levels(...levels) - Filter enabled log levels
• .silent() - Suppress all output

💡 Examples

Basic Logging

import { plip } from '@ru-dr/plip';

// Simple messages
plip.info("Server starting on port 3000");
plip.success("Database connected successfully");

// With data
plip.info("New user registered:", { email: "user@example.com", id: 123 });
plip.error("Authentication failed:", { reason: "invalid_token", userId: 456 });

Context-Aware Logging

import { plip } from '@ru-dr/plip';

// Create context-aware loggers for different scopes
const authLogger = plip.withContext({ scope: "auth" });
const dbLogger = plip.withContext({ scope: "database", pool: "primary" });
const apiLogger = plip.withContext({ scope: "api", version: "v1" });

// All logs will include the context automatically
authLogger.info("User login attempt", { userId: 123, method: "oauth" });
// Output: 🫧 [INFO] User login attempt {"scope":"auth","userId":123,"method":"oauth"}

dbLogger.warn("Connection pool high usage", { activeConnections: 45 });
// Output: ⚠️ [WARN] Connection pool high usage {"scope":"database","pool":"primary","activeConnections":45}

// Context can be chained and extended
const requestLogger = apiLogger.withContext({ requestId: "req-789" });
requestLogger.error("Request processing failed", { endpoint: "/users" });
// Output: 💥 [ERROR] Request processing failed {"scope":"api","version":"v1","requestId":"req-789","endpoint":"/users"}

Environment-Specific Logging

import { createPlip } from '@ru-dr/plip';

// Development logger - verbose and colorful
const devLogger = createPlip({
  enabledLevels: ['debug', 'trace', 'info', 'warn', 'error'],
  enableEmojis: true,
  enableColors: true
});

// Production logger - errors and warnings only
const prodLogger = createPlip({
  enabledLevels: ['warn', 'error'],
  enableEmojis: false,
  enableColors: false,
  enableSyntaxHighlighting: false
});

// Use based on environment
const logger = process.env.NODE_ENV === 'production' ? prodLogger : devLogger;

Custom Themes

import { createPlip, colors } from '@ru-dr/plip';

const logger = createPlip({
  theme: {
    emojis: {
      info: "📘",
      success: "✅", 
      warn: "⚠️",
      error: "❌"
    },
    colors: {
      info: colors.blue,
      success: colors.green,
      warn: colors.yellow,
      error: colors.red
    }
  }
});

Conditional Logging

import { createPlip } from '@ru-dr/plip';

// Only log in development
const debugLogger = createPlip({
  devOnly: true,
  enabledLevels: ['debug', 'trace']
});

// Log everything except in production
const logger = createPlip({
  enabledLevels: process.env.NODE_ENV === 'production' 
    ? ['warn', 'error'] 
    : ['debug', 'info', 'warn', 'error']
});

🌐 SSR vs CSR Logging

Plip provides optimized configurations for both Server-Side Rendering (SSR) and Client-Side Rendering (CSR) environments. CSR is the default for the best modern web development experience.

Quick Usage

import { plip, createSSRLogger, createCSRLogger } from '@ru-dr/plip';

// Default logger uses CSR configuration (with emojis & colors)
plip.info("Hello world!"); // 🫧 [INFO] Hello world!

// Explicit SSR logger (optimized for servers)
const serverLogger = createSSRLogger();
serverLogger.info("Server started", { port: 3000 }); 
// Output: [INFO] Server started {"port":3000}

// Explicit CSR logger (optimized for browsers) 
const clientLogger = createCSRLogger();
clientLogger.success("User logged in", { userId: 123 });
// Output: 🎉 [SUCCESS] User logged in {"userId":123}

Key Differences

Framework Examples

// Next.js API Route (SSR)
import { createSSRLogger } from '@ru-dr/plip';
const serverLogger = createSSRLogger();

export default function handler(req, res) {
  serverLogger.info("API request", { method: req.method, url: req.url });
}

// React Component (CSR)  
import { createCSRLogger } from '@ru-dr/plip';
const clientLogger = createCSRLogger();

function App() {
  useEffect(() => {
    clientLogger.success("App loaded"); // 🎉 [SUCCESS] App loaded
  }, []);
}

📖 Learn More: Check out our SSR vs CSR Guide for detailed examples and best practices.

import { createPlip } from '@ru-dr/plip';

// Only log in development const debugLogger = createPlip({ devOnly: true });

// Custom conditions const logger = createPlip({ enabledLevels: process.env.DEBUG ? 'debug', 'trace', 'info', 'warn', 'error' : 'warn', 'error' });

## 🛠️ Advanced Usage

### TypeScript Integration
```typescript
import { PlipConfig, LogLevel, createPlip } from '@ru-dr/plip';

// Type-safe configuration
const config: PlipConfig = {
  enabledLevels: ['info', 'error'] as LogLevel[],
  enableColors: true,
  theme: {
    emojis: {
      info: "💡",
      error: "🚨"
    }
  }
};

const logger = createPlip(config);

Framework Integration

Express.js Middleware

import express from 'express';
import { createPlip } from '@ru-dr/plip';

const logger = createPlip();
const app = express();

app.use((req, res, next) => {
  logger.info(`${req.method} ${req.path}`, {
    ip: req.ip,
    userAgent: req.get('User-Agent')
  });
  next();
});

Error Handling

import { createPlip } from '@ru-dr/plip';

const logger = createPlip();

process.on('uncaughtException', (error) => {
  logger.error('Uncaught Exception:', {
    message: error.message,
    stack: error.stack,
    timestamp: new Date().toISOString()
  });
  process.exit(1);
});

try {
  // Your application logic
} catch (error) {
  logger.error('Application error:', error);
}

📚 Learn More

Explore our comprehensive documentation to master Plip Logger:

📖 Guides

• Basic Usage - Learn the fundamentals
• Configuration - Customize Plip to your needs
• SSR vs CSR - Server-side and client-side optimized configurations
• Best Practices - Write better logs

💡 Examples & Patterns

• Custom Loggers - Context-aware logging and advanced patterns
• Integration Examples - Framework-specific implementations
• Production Setup - Production-ready configurations
• SSR/CSR Quick Start - Get started with server/client logging

🔧 Integrations

• Express.js - Express middleware and patterns
• Next.js - Next.js SSR/CSR integration
• NestJS - NestJS dependency injection
• Database Logging - Database query logging

📋 API Reference

• Logger API - Complete method reference
• Configuration - All configuration options
• Types - TypeScript definitions

💡 Pro Tip: Start with Custom Loggers to learn context-aware logging with plip.withContext({ scope: "auth" })

🤝 Contributing

We love contributions! Here's how you can help make Plip even better:

🐛 Found a Bug?

• Check if it's already reported in Issues
• If not, create a new issue with:
  • Clear description of the problem
  • Steps to reproduce
  • Expected vs actual behavior
  • Your environment details

💡 Have an Idea?

• Open a feature request
• Join our discussions
• Check our roadmap for planned features

🔧 Want to Code?

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/plip.git
3. Create a branch: git checkout -b feature/amazing-feature
4. Install dependencies: bun install
5. Make your changes
6. Test your changes: bun test
7. Build the project: bun run build
8. Commit your changes: git commit -m 'Add amazing feature'
9. Push to your branch: git push origin feature/amazing-feature
10. Open a Pull Request

📝 Development Setup

# Clone the repository
git clone https://github.com/ru-dr/plip.git
cd plip

# Install dependencies
bun install

# Run tests
bun test

# Run tests in watch mode
bun test --watch

# Build the project
bun run build

# Test your changes
bun run dev

🧪 Testing

We use Bun for testing. Please ensure:

• All tests pass: bun test
• Add tests for new features
• Maintain or improve code coverage
• Follow existing test patterns

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

TL;DR: You can use, modify, and distribute this project freely. Just keep the copyright notice! 😊

Made with ❤️ by ru-dr

⭐ Star this repo if you find it useful! ⭐

Report Bug • Request Feature • Discussions