clarity

Clarity is a modern logging & debugging client for TypeScript, offering powerful features for both development and production environments.

Features

🎨 Rich Colored Output

const logger = new Logger('app')

logger.info('Starting application...') // Blue output
logger.success('Setup complete') // Green output
logger.warning('Cache miss') // Yellow output
logger.error('Connection failed') // Red output

⚡ Performance Tracking

const logger = new Logger('performance')
const end = logger.info('Starting expensive operation...')

// ... do work ...

end('Operation completed') // automatically includes time taken

🔍 Domain-specific Logging

const logger = new Logger('api')
const authLogger = logger.extend('auth')
const dbLogger = logger.extend('db')

authLogger.info('User authenticated') // [api:auth] info
dbLogger.warning('Connection slow') // [api:db] warning

📊 Log Management

# Watch logs in real-time
clarity watch --level error --name "api:*"

# Search through logs
clarity search "connection failed" --level error

# Export logs
clarity export --format json --output logs.json

# Follow last 50 lines
clarity tail --lines 50 --follow

Installation

bun install -d clarity

Quick Start

Basic Usage

import { Logger } from 'clarity'

const logger = new Logger('app')

logger.info('Application starting...')
logger.success('Server listening on port 3000')

try {
  // ... some operation
}
catch (error) {
  logger.error('Failed to start server:', error)
}

Advanced Features

// Performance tracking
const end = logger.info('Starting database migration...')
await runMigrations()
end('Migration completed')

// Domain-specific logging
const dbLogger = logger.extend('db')
const authLogger = logger.extend('auth')

dbLogger.info('Connected to database')
authLogger.warning('Rate limit reached')

// Debug mode for development
logger.debug('SQL query:', query)

Using the CLI

# Watch logs in real-time
clarity watch --level debug --name "api:*"

# Export error logs
clarity export --level error --output errors.json

# Search through logs
clarity search "failed to connect" --level error

# Show and follow last 50 lines
clarity tail --lines 50 --follow

# Clear old logs
clarity clear --before 2024-01-01

# Manage configuration
clarity config set --level debug

Ready to dive deeper? Check out our CLI Guide or Configuration Guide for more details.

Testing

bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

Two things are true: Stacks OSS will always stay open-source, and we do love to receive postcards from wherever Stacks is used! We also publish them on our website.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

Credits

• debug
• @open-draft/logger
• Chris Breuer
• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙