@oxog/pigment

Zero-dependency terminal styling with micro-kernel architecture and Chalk drop-in compatibility.

Features

• Zero Dependencies - No external packages, implements everything from scratch
• Universal Runtime - Works in Node.js and browsers with same API
• Micro-Kernel Architecture - Powerful plugin system for extensibility
• Chalk Compatible - Drop-in replacement for Chalk v5
• Multiple API Styles - Proxy chaining, function composition, builder pattern
• Full Color Support - 16 base colors, 256 colors, true color (RGB/HEX/HSL)
• Environment Aware - Respects NO_COLOR, FORCE_COLOR, TTY detection
• TypeScript - Strict mode with full type safety
• Tree Shakeable - Optimize bundle size with individual imports

Installation

npm install @oxog/pigment

Quick Start

Proxy-Based Chaining API (Primary)

import { pigment } from '@oxog/pigment';

// Chain styles naturally
pigment.bold.red('Error!');
pigment.italic.blue.bgWhite('Info');
pigment.underline.yellow('Warning');

// Nested styles
pigment.red(`Error: ${pigment.bold('critical')} issue`);

Function Composition API (Tree-Shakeable)

import { bold, red, compose } from '@oxog/pigment';

// Compose styles
const error = compose(bold, red);
console.log(error('Something went wrong'));

// Reusable styles
const highlight = compose(bold, red);
console.log(highlight('IMPORTANT'));

Builder Pattern API

import { createPigment } from '@oxog/pigment';

const styled = createPigment()
  .bold()
  .red()
  .bgWhite()
  .paint('Styled text');

console.log(styled);

Chalk Drop-in Compatibility

// Before (Chalk)
import chalk from 'chalk';
console.log(chalk.red.bold('Error'));

// After (Pigment) - just change import
import chalk from '@oxog/pigment';
console.log(chalk.red.bold('Error'));

Colors

16 Base Colors

pigment.black('text');
pigment.red('text');
pigment.green('text');
pigment.yellow('text');
pigment.blue('text');
pigment.magenta('text');
pigment.cyan('text');
pigment.white('text');

Bright Variants

pigment.blackBright('text');  // alias: gray
pigment.redBright('text');
pigment.greenBright('text');
pigment.yellowBright('text');
pigment.blueBright('text');
pigment.magentaBright('text');
pigment.cyanBright('text');
pigment.whiteBright('text');

Background Colors

pigment.bgRed('text');
pigment.bgGreen('text');
pigment.bgBlue('text');
pigment.bgYellow('text');
// ... all 16 colors
pigment.bgRedBright('text');

Modifiers

pigment.bold('Bold text');
pigment.dim('Dimmed text');
pigment.italic('Italic text');
pigment.underline('Underlined text');
pigment.strikethrough('Strikethrough text');
pigment.inverse('Inverse colors');
pigment.hidden('Hidden text');
pigment.reset('Reset all styles');

Extended Colors

ANSI 256

pigment.ansi256(196)('Bright red');
pigment.bgAnsi256(21)('Blue background');

True Color (RGB)

pigment.rgb(255, 136, 0)('Orange text');
pigment.bgRgb(0, 120, 255)('Blue background');

HEX Colors

pigment.hex('#FF8800')('Orange text');
pigment.bgHex('#0078FF')('Blue background');

HSL Colors

pigment.hsl(30, 100, 50)('Orange text');
pigment.bgHsl(210, 100, 50)('Blue background');

Environment Detection

import { pigment, supportsColor, resetColorSupportCache } from '@oxog/pigment';

// Check color support
console.log(supportsColor);
// { level: 3, hasBasic: true, has256: true, has16m: true }

// Override level
const pigment = createPigment({ level: 3 });

// Reset cached detection (useful for testing)
resetColorSupportCache();

Environment Variables

• NO_COLOR - Disables all colors
• FORCE_COLOR - Forces color level (0, 1, 2, 3)
• TERM - Terminal type detection

Plugin System

Core Plugins (Always Loaded)

// 16 ANSI colors
baseColorsPlugin

// Text modifiers
modifiersPlugin

// 256-color palette
ansi256Plugin

// RGB/HEX/HSL color support
trueColorPlugin

// Nested/composed styles
nestingPlugin

// Environment detection
environmentPlugin

Optional Plugins (Opt-in)

Gradient Plugin

import { createPigment } from '@oxog/pigment';
import { gradientPlugin } from '@oxog/pigment/plugins';

const pigment = createPigment({ plugins: [gradientPlugin({ steps: 10 })] });

// Linear gradient
pigment.gradient('red', 'blue')('Gradient text');
pigment.gradient('#FF0000', '#0000FF')('Hex gradient');
pigment.gradient([255, 0, 0], [0, 0, 255])('RGB gradient');

// Rainbow gradient
pigment.rainbow('Rainbow text');

Theme Plugin

import { themePlugin } from '@oxog/pigment/plugins';

const pigment = createPigment({ plugins: [themePlugin({ preset: 'monokai' })] });

// Theme colors
pigment.theme.keyword('const');      // Orange
pigment.theme.string('"hello"');     // Yellow
pigment.theme.number('42');          // Purple
pigment.theme.comment('// note');    // Gray
pigment.theme.error('Error!');       // Red
pigment.theme.success('Done!');      // Green

Available Presets: monokai, dracula, nord, github, vscode, tokyo-night, catppuccin, one-dark, solarized

Semantic Plugin

import { semanticPlugin } from '@oxog/pigment/plugins';

const pigment = createPigment({ plugins: [semanticPlugin()] });

pigment.success('✓ Task completed');    // Green
pigment.error('✗ Task failed');         // Red
pigment.warning('⚠ Check this');        // Yellow
pigment.info('ℹ Note');                 // Blue
pigment.debug('[DEBUG] value');         // Gray

// Custom colors
semanticPlugin({
  success: '#00FF00',
  error: '#FF0000',
  warning: '#FFAA00',
  info: '#00AAFF',
  debug: '#888888'
})

Box Plugin

import { boxPlugin } from '@oxog/pigment/plugins';

const pigment = createPigment({ plugins: [boxPlugin()] });

// Simple box
pigment.box('Hello World');
// ┌─────────────┐
// │ Hello World │
// └─────────────┘

// Styled box
pigment.box('Error!', { border: 'double', padding: 2 });
// ╔═════════════╗
// ║               ║
// ║    Error!     ║
// ║               ║
// ╚═════════════╝

Border Styles: single, double, rounded, bold, classic

Template Plugin

import { templatePlugin } from '@oxog/pigment/plugins';

const pigment = createPigment({ plugins: [templatePlugin()] });

// Tagged template
console.log(pigment`{red Error:} {bold ${name}} has {yellow ${count}} issues`);

// Nested styles
console.log(pigment`{bold.red CRITICAL:} {dim system failure}`);

Ecosystem Plugin

import { pigmentPlugin } from '@oxog/pigment/plugins';

// For @oxog/log, @oxog/cli
log.use(pigmentPlugin({ theme: 'monokai', level: 3 }));

API Reference

createPigment

import { createPigment } from '@oxog/pigment';

const pigment = createPigment({
  level: 3,              // Force color level
  forceColor: false,     // Force color output
  noColor: false,        // Disable all colors
  plugins: []            // Custom plugins
});

Type Definitions

interface Pigment {
  // Text modifiers
  bold: Pigment;
  dim: Pigment;
  italic: Pigment;
  // ... all modifiers

  // Foreground colors
  black: Pigment;
  red: Pigment;
  green: Pigment;
  // ... all colors

  // Background colors
  bgBlack: Pigment;
  bgRed: Pigment;
  // ... all background colors

  // Extended colors
  ansi256(code: number): Pigment;
  rgb(r: number, g: number, b: number): Pigment;
  hex(color: string): Pigment;
  hsl(h: number, s: number, l: number): Pigment;

  // Function call
  (text: string): string;
}

Platform Support

| Platform | Output | Auto-Detection | |----------|---------|---------------| | Node.js | ANSI escape codes | ✅ TTY, TERM, CI | | Browser | CSS %c styling | ✅ Browser API |

Technical Specifications

| Requirement | Value | |-------------|-------| | Runtime | Universal (Node.js + Browser) | | Module Format | ESM + CJS | | Node.js | >= 18 | | TypeScript | >= 5.0 | | Bundle (core) | < 3KB gzipped | | Bundle (all plugins) | < 12KB gzipped | | Test Coverage | 100% target |

Dependencies

{
  "dependencies": {
    "@oxog/types": "^1.0.1",
    "@oxog/plugin": "^1.0.0"
  }
}

@oxog ecosystem only - Only @oxog packages as dependencies, no external libraries.

License

MIT © Ersin Koç

Links

• GitHub
• Website
• npm

Made with ❤️ by Ersin KOÇ