LogsDX

Beautiful, consistent log styling for terminal and browser environments.

LogsDX is a schema-based theming engine that applies consistent visual styling to logs across all environments—write themes once, style logs everywhere.

Features

Unified Theming - One theme works in terminal, browser, and CI/CD
Zero Dependencies - Works with any existing logger
8+ Built-in Themes - Production-ready themes included
CLI Tool - Process log files with beautiful formatting
Accessible - WCAG compliance checking built-in
Light/Dark Mode - Automatic theme adaptation

Installation

# npm
npm install logsdx

# bun (recommended for development)
bun add logsdx

# yarn
yarn add logsdx

# pnpm
pnpm add logsdx

Requirements: Node.js 18+ or Bun 1.0+

Getting Started

1. Basic Usage - Style Your Console Logs

import { getLogsDX } from "logsdx";

// Initialize with a built-in theme
const logger = getLogsDX("dracula");

// Style a log line
console.log(
  logger.processLine(
    "ERROR: Database connection failed at 2024-01-15T10:30:45Z",
  ),
);
// Output: Styled text with ERROR in red, timestamp in dim gray

2. Process Multiple Lines

const logs = [
  "INFO: Server started on port 3000",
  "WARN: Memory usage above 80%",
  "ERROR: Failed to connect to database",
];

// Process all lines at once
const styledLogs = logger.processLines(logs);
styledLogs.forEach((line) => console.log(line));

3. Browser Integration (React Example)

import { LogsDX } from "logsdx";

function LogViewer({ logs }) {
  const logger = LogsDX.getInstance({
    theme: "dracula",
    outputFormat: "html",
    htmlStyleFormat: "css",
  });

  return (
    <div className="log-container">
      {logs.map((log, i) => (
        <div
          key={i}
          dangerouslySetInnerHTML={{ __html: logger.processLine(log) }}
        />
      ))}
    </div>
  );
}

4. Use Different Output Formats

// Terminal output with ANSI colors
const terminalLogger = getLogsDX("dracula", {
  outputFormat: "ansi",
});

// HTML with inline styles
const htmlLogger = getLogsDX("dracula", {
  outputFormat: "html",
  htmlStyleFormat: "css",
});

// HTML with CSS classes
const classLogger = getLogsDX("dracula", {
  outputFormat: "html",
  htmlStyleFormat: "className",
});

const line = "ERROR: Connection timeout";
console.log(terminalLogger.processLine(line)); // \x1b[31;1mERROR\x1b[0m: Connection timeout
console.log(htmlLogger.processLine(line)); // <span style="color:#ff5555;font-weight:bold">ERROR</span>: Connection timeout
console.log(classLogger.processLine(line)); // <span class="logsdx-error logsdx-bold">ERROR</span>: Connection timeout

CLI Usage

After installation, the logsdx CLI tool is available globally:

Setup & Basic Commands

# Process a log file with default theme
logsdx server.log

# Use a specific theme
logsdx server.log --theme nord

# Save formatted output
logsdx server.log --output formatted.log

# Process from stdin
tail -f app.log | logsdx

# List all available themes
logsdx --list-themes

Real-World Examples

# Format nginx access logs
logsdx /var/log/nginx/access.log --theme github-dark

# Process Docker logs
docker logs my-container | logsdx --theme dracula

# Format and save application logs
logsdx app.log --theme nord --output styled-app.log

# Debug mode for troubleshooting
logsdx app.log --debug

Creating Custom Themes

Method 1: Using the Theme Creator (Interactive)

bun run create-theme

This launches an interactive wizard that helps you:

Choose color presets (Vibrant, Pastel, Neon, etc.)
Preview your theme in real-time
Check WCAG accessibility compliance
Export to JSON or TypeScript

Method 2: Define Programmatically

import { createTheme, registerTheme } from "logsdx";

const myTheme = createTheme({
  name: "my-company-theme",
  mode: "dark",
  schema: {
    defaultStyle: {
      color: "#e0e0e0",
    },
    matchWords: {
      ERROR: { color: "#ff5555", styleCodes: ["bold"] },
      WARN: { color: "#ffaa00" },
      INFO: { color: "#00aaff" },
      DEBUG: { color: "#888888", styleCodes: ["dim"] },
    },
    matchPatterns: [
      {
        name: "timestamp",
        pattern: "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}",
        options: { color: "#666666", styleCodes: ["italic"] },
      },
      {
        name: "ip-address",
        pattern: "\\b(?:\\d{1,3}\\.){3}\\d{1,3}\\b",
        options: { color: "#ff00ff" },
      },
    ],
    matchStartsWith: {
      "[": { color: "#aaaaaa" },
      "{": { color: "#00ff00" },
    },
  },
});

// Register and use the theme
registerTheme(myTheme);
const logger = getLogsDX("my-company-theme");

Method 3: JSON Configuration File

Create my-theme.json:

{
  "name": "production",
  "mode": "dark",
  "schema": {
    "defaultStyle": {
      "color": "#ffffff"
    },
    "matchWords": {
      "ERROR": {
        "color": "#ff4444",
        "styleCodes": ["bold", "underline"]
      },
      "SUCCESS": {
        "color": "#00ff00",
        "styleCodes": ["bold"]
      }
    },
    "matchPatterns": [
      {
        "name": "uuid",
        "pattern": "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
        "options": {
          "color": "#cyan",
          "styleCodes": ["italic"]
        }
      }
    ]
  }
}

Load and use:

import theme from "./my-theme.json";
const logger = getLogsDX(theme);

Integration with Popular Loggers

LogsDX works as a styling layer on top of any logger:

Winston

import winston from "winston";
import { getLogsDX } from "logsdx";

const logsDX = getLogsDX("dracula");

const logger = winston.createLogger({
  format: winston.format.printf((info) => {
    const message = `${info.level.toUpperCase()}: ${info.message}`;
    return logsDX.processLine(message);
  }),
  transports: [new winston.transports.Console()],
});

logger.info("Application started");
logger.error("Database connection failed");

Pino

import pino from "pino";
import { getLogsDX } from "logsdx";

const logsDX = getLogsDX("nord");

const logger = pino({
  transport: {
    target: "pino-pretty",
    options: {
      messageFormat: (log, messageKey) => {
        const msg = log[messageKey];
        return logsDX.processLine(msg);
      },
    },
  },
});

Console Override (Global)

import { getLogsDX } from "logsdx";

const logsDX = getLogsDX("github-dark");
const originalLog = console.log;

console.log = (...args) => {
  const message = args.join(" ");
  originalLog(logsDX.processLine(message));
};

// Now all console.log calls are styled
console.log("ERROR: Something went wrong");
console.log("INFO: Process completed");

API Reference

Core Functions

`getLogsDX(theme, options?)`

Returns a LogsDX instance configured with the specified theme.

const logger = getLogsDX("dracula", {
  outputFormat: "ansi", // "ansi" | "html"
  htmlStyleFormat: "css", // "css" | "className"
  debug: false, // Enable debug output
});

`LogsDX.getInstance(config)`

Singleton pattern for getting a LogsDX instance.

const logger = LogsDX.getInstance({
  theme: "nord",
  outputFormat: "html",
});

Instance Methods

`processLine(line: string): string`

Process a single log line with theme styling.

`processLines(lines: string[]): string[]`

Process multiple log lines at once.

`processLog(text: string): string`

Process a multi-line log string (splits by newlines).

Theme Management

`getAllThemes(): Theme[]`

Get all available themes.

`getThemeNames(): string[]`

Get names of all available themes.

`getTheme(name: string): Theme | undefined`

Get a specific theme by name.

`registerTheme(theme: Theme): void`

Register a custom theme for use.

`validateTheme(theme: Theme): ValidationResult`

Validate theme schema and check for errors.

Configuration Options

Option	Type	Default	Description
`theme`	`string \| Theme`	`"oh-my-zsh"`	Theme name or custom theme object
`outputFormat`	`"ansi" \| "html"`	`"ansi"`	Output format for styled text
`htmlStyleFormat`	`"css" \| "className"`	`"css"`	HTML styling method
`debug`	`boolean`	`false`	Enable debug output

Style Codes

Available style codes for text decoration:

bold - Bold text
italic - Italic text
underline - Underlined text
dim - Dimmed/faded text
blink - Blinking text (terminal support varies)
reverse - Reversed colors
strikethrough - Strikethrough text

Pattern Matching Priority

LogsDX applies styles in this priority order (highest to lowest):

matchWords - Exact word matches
matchPatterns - Regular expression patterns
matchStartsWith - String prefix matches
matchEndsWith - String suffix matches
matchContains - Substring matches
defaultStyle - Fallback style

Built-in Themes

Theme	Mode	Description
`oh-my-zsh`	Dark	Popular Oh My Zsh terminal theme
`dracula`	Dark	Dracula color scheme
`nord`	Dark	Arctic, north-bluish theme
`monokai`	Dark	Classic Monokai colors
`github-dark`	Dark	GitHub's dark mode
`github-light`	Light	GitHub's default light theme
`solarized-dark`	Dark	Solarized dark variant
`solarized-light`	Light	Solarized light variant

Advanced Features

Light Box Rendering

For light themes in dark terminals, use the light box renderer:

import { renderLightBox, isLightTheme } from "logsdx";

if (isLightTheme("github-light")) {
  const output = renderLightBox(
    ["INFO: Server started", "WARN: High memory"],
    "github-light",
    "Server Logs",
    {
      width: 80,
      padding: 2,
      borderStyle: "rounded",
    },
  );
  console.log(output);
}

WCAG Accessibility Compliance

import { checkWCAGCompliance, adjustThemeForAccessibility } from "logsdx";

// Check theme accessibility
const compliance = checkWCAGCompliance(myTheme);
console.log(compliance); // "AAA" | "AA" | "A" | "FAIL"

// Auto-fix contrast issues
const accessibleTheme = adjustThemeForAccessibility(myTheme, 4.5);

CSS Generation

Generate CSS for web applications:

import { generateCompleteCSS } from "logsdx";

const { bem, utilities, tailwind } = generateCompleteCSS(theme);

// Use generated CSS in your app
// bem: BEM-style classes (.logsdx__error)
// utilities: Utility classes (.text-red-500)
// tailwind: Tailwind config extension

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/yowainwright/logsdx.git
cd logsdx

# Run setup script (installs dependencies, builds, configures git hooks)
bun run setup

# Start development server with mprocs (runs site + tests in watch mode)
bun run dev

# Or run individual commands:
bun test              # Run tests
bun run build         # Build the project
bun run lint          # Check code quality
bun run format        # Format code

The setup script will:

Install all dependencies
Build the main package
Configure git hooks (pre-commit, post-merge, post-checkout)
Verify your environment is ready

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
.github		.github
docs		docs
scripts		scripts
site		site
src		src
tests		tests
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
codecov.yml		codecov.yml
mise.toml		mise.toml
mprocs.yaml		mprocs.yaml
oxlintrc.json		oxlintrc.json
package.json		package.json
schema.json		schema.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json

License

yowainwright/logsdx

Folders and files

Latest commit

History

Repository files navigation

LogsDX

Features

Installation

Getting Started

1. Basic Usage - Style Your Console Logs

2. Process Multiple Lines

3. Browser Integration (React Example)

4. Use Different Output Formats

CLI Usage

Setup & Basic Commands

Real-World Examples

Creating Custom Themes

Method 1: Using the Theme Creator (Interactive)

Method 2: Define Programmatically

Method 3: JSON Configuration File

Integration with Popular Loggers

Winston

Pino

Console Override (Global)

API Reference

Core Functions

getLogsDX(theme, options?)

LogsDX.getInstance(config)

Instance Methods

processLine(line: string): string

processLines(lines: string[]): string[]

processLog(text: string): string

Theme Management

getAllThemes(): Theme[]

getThemeNames(): string[]

getTheme(name: string): Theme | undefined

registerTheme(theme: Theme): void

validateTheme(theme: Theme): ValidationResult

Configuration Options

Style Codes

Pattern Matching Priority

Built-in Themes

Advanced Features

Light Box Rendering

WCAG Accessibility Compliance

CSS Generation

Contributing

Development Setup

License

Support

About

Topics

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

`getLogsDX(theme, options?)`

`LogsDX.getInstance(config)`

`processLine(line: string): string`

`processLines(lines: string[]): string[]`

`processLog(text: string): string`

`getAllThemes(): Theme[]`

`getThemeNames(): string[]`

`getTheme(name: string): Theme | undefined`

`registerTheme(theme: Theme): void`

`validateTheme(theme: Theme): ValidationResult`

Packages