CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-colorette

Lightweight, high-performance terminal string styling library that enables developers to add colors, text formatting, and visual effects to command-line interfaces.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Colorette

Colorette is a lightweight, high-performance terminal string styling library that enables developers to add colors, text formatting, and visual effects to command-line interfaces. It provides comprehensive ANSI escape code support with automatic terminal color capability detection, zero dependencies, and performance optimization.

Package Information

  • Package Name: colorette
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install colorette

Core Imports

import { red, bold, blue, isColorSupported, createColors } from "colorette";

For CommonJS:

const { red, bold, blue, isColorSupported, createColors } = require("colorette");

Full namespace import:

import * as c from "colorette";

Basic Usage

import { blue, bold, underline, red, green } from "colorette";

// Basic text styling
console.log(red("Error: Something went wrong"));
console.log(green("Success: Operation completed"));
console.log(bold("Important message"));

// Chainable/nestable styling
console.log(bold(red("Critical Error")));
console.log(blue(`The ${underline("quick")} brown fox`));

// Complex nesting with proper escape sequence handling
console.log(bold(`I'm ${blue(`da ba ${underline("dee")} da ba`)} daa`));

// Custom color configuration
import { createColors } from "colorette";
const { blue: customBlue } = createColors({ useColor: false });
console.log(customBlue("This won't be colored"));

Architecture

Colorette is built around several key components:

  • Color Detection: Automatic terminal color capability detection via environment variables, CLI flags, terminal capabilities, and CI environment recognition
  • ANSI Escape Codes: Efficient ANSI escape sequence generation with bleeding prevention
  • Factory Pattern: createColors() function for creating custom color instances with overridden settings
  • Performance Optimization: Efficient string replacement algorithms using index-based substring operations and recursive bleeding prevention for nested color sequences
  • Zero Dependencies: No external dependencies for maximum compatibility and minimal bundle size

Capabilities

Color Support Detection

Check whether the current terminal environment supports colors.

/**
 * Boolean constant indicating whether the current terminal supports colors
 * Automatically detected based on environment variables, CLI flags, and terminal capabilities
 */
const isColorSupported: boolean;

Color Factory

Create custom color instances with overridden color support settings.

/**
 * Creates a colorette instance with custom color support configuration
 * @param options - Configuration options
 * @param options.useColor - Override automatic color detection
 * @returns Object containing all color functions with applied configuration
 */
function createColors(options?: { useColor?: boolean }): Colorette;

interface Colorette {
  reset: Color;
  bold: Color;
  dim: Color;
  italic: Color;
  underline: Color;
  inverse: Color;
  hidden: Color;
  strikethrough: Color;
  black: Color;
  red: Color;
  green: Color;
  yellow: Color;
  blue: Color;
  magenta: Color;
  cyan: Color;
  white: Color;
  gray: Color;
  bgBlack: Color;
  bgRed: Color;
  bgGreen: Color;
  bgYellow: Color;
  bgBlue: Color;
  bgMagenta: Color;
  bgCyan: Color;
  bgWhite: Color;
  blackBright: Color;
  redBright: Color;
  greenBright: Color;
  yellowBright: Color;
  blueBright: Color;
  magentaBright: Color;
  cyanBright: Color;
  whiteBright: Color;
  bgBlackBright: Color;
  bgRedBright: Color;
  bgGreenBright: Color;
  bgYellowBright: Color;
  bgBlueBright: Color;
  bgMagentaBright: Color;
  bgCyanBright: Color;
  bgWhiteBright: Color;
}

Text Modifiers

Apply text formatting effects to strings.

/**
 * Reset all formatting and colors
 * @param text - Text to reset
 * @returns Formatted string with reset codes
 */
const reset: Color;

/**
 * Apply bold text styling
 * @param text - Text to make bold
 * @returns String with bold ANSI codes
 */
const bold: Color;

/**
 * Apply dim/faint text styling
 * @param text - Text to dim
 * @returns String with dim ANSI codes
 */
const dim: Color;

/**
 * Apply italic text styling
 * @param text - Text to italicize
 * @returns String with italic ANSI codes
 */
const italic: Color;

/**
 * Apply underlined text styling
 * @param text - Text to underline
 * @returns String with underline ANSI codes
 */
const underline: Color;

/**
 * Invert foreground and background colors
 * @param text - Text to invert
 * @returns String with inverse ANSI codes
 */
const inverse: Color;

/**
 * Hide text (make invisible)
 * @param text - Text to hide
 * @returns String with hidden ANSI codes
 */
const hidden: Color;

/**
 * Apply strikethrough text styling
 * @param text - Text to strikethrough
 * @returns String with strikethrough ANSI codes
 */
const strikethrough: Color;

Foreground Colors

Apply foreground text colors.

/**
 * Apply black text color
 * @param text - Text to color
 * @returns String with black color ANSI codes
 */
const black: Color;

/**
 * Apply red text color
 * @param text - Text to color
 * @returns String with red color ANSI codes
 */
const red: Color;

/**
 * Apply green text color
 * @param text - Text to color
 * @returns String with green color ANSI codes
 */
const green: Color;

/**
 * Apply yellow text color
 * @param text - Text to color
 * @returns String with yellow color ANSI codes
 */
const yellow: Color;

/**
 * Apply blue text color
 * @param text - Text to color
 * @returns String with blue color ANSI codes
 */
const blue: Color;

/**
 * Apply magenta text color
 * @param text - Text to color
 * @returns String with magenta color ANSI codes
 */
const magenta: Color;

/**
 * Apply cyan text color
 * @param text - Text to color
 * @returns String with cyan color ANSI codes
 */
const cyan: Color;

/**
 * Apply white text color
 * @param text - Text to color
 * @returns String with white color ANSI codes
 */
const white: Color;

/**
 * Apply gray text color
 * @param text - Text to color
 * @returns String with gray color ANSI codes
 */
const gray: Color;

Background Colors

Apply background colors to text.

/**
 * Apply black background color
 * @param text - Text to apply background to
 * @returns String with black background ANSI codes
 */
const bgBlack: Color;

/**
 * Apply red background color
 * @param text - Text to apply background to
 * @returns String with red background ANSI codes
 */
const bgRed: Color;

/**
 * Apply green background color
 * @param text - Text to apply background to
 * @returns String with green background ANSI codes
 */
const bgGreen: Color;

/**
 * Apply yellow background color
 * @param text - Text to apply background to
 * @returns String with yellow background ANSI codes
 */
const bgYellow: Color;

/**
 * Apply blue background color
 * @param text - Text to apply background to
 * @returns String with blue background ANSI codes
 */
const bgBlue: Color;

/**
 * Apply magenta background color
 * @param text - Text to apply background to
 * @returns String with magenta background ANSI codes
 */
const bgMagenta: Color;

/**
 * Apply cyan background color
 * @param text - Text to apply background to
 * @returns String with cyan background ANSI codes
 */
const bgCyan: Color;

/**
 * Apply white background color
 * @param text - Text to apply background to
 * @returns String with white background ANSI codes
 */
const bgWhite: Color;

Bright Foreground Colors

Apply bright/intense foreground text colors.

/**
 * Apply bright black text color
 * @param text - Text to color
 * @returns String with bright black color ANSI codes
 */
const blackBright: Color;

/**
 * Apply bright red text color
 * @param text - Text to color
 * @returns String with bright red color ANSI codes
 */
const redBright: Color;

/**
 * Apply bright green text color
 * @param text - Text to color
 * @returns String with bright green color ANSI codes
 */
const greenBright: Color;

/**
 * Apply bright yellow text color
 * @param text - Text to color
 * @returns String with bright yellow color ANSI codes
 */
const yellowBright: Color;

/**
 * Apply bright blue text color
 * @param text - Text to color
 * @returns String with bright blue color ANSI codes
 */
const blueBright: Color;

/**
 * Apply bright magenta text color
 * @param text - Text to color
 * @returns String with bright magenta color ANSI codes
 */
const magentaBright: Color;

/**
 * Apply bright cyan text color
 * @param text - Text to color
 * @returns String with bright cyan color ANSI codes
 */
const cyanBright: Color;

/**
 * Apply bright white text color
 * @param text - Text to color
 * @returns String with bright white color ANSI codes
 */
const whiteBright: Color;

Bright Background Colors

Apply bright/intense background colors to text.

/**
 * Apply bright black background color
 * @param text - Text to apply background to
 * @returns String with bright black background ANSI codes
 */
const bgBlackBright: Color;

/**
 * Apply bright red background color
 * @param text - Text to apply background to
 * @returns String with bright red background ANSI codes
 */
const bgRedBright: Color;

/**
 * Apply bright green background color
 * @param text - Text to apply background to
 * @returns String with bright green background ANSI codes
 */
const bgGreenBright: Color;

/**
 * Apply bright yellow background color
 * @param text - Text to apply background to
 * @returns String with bright yellow background ANSI codes
 */
const bgYellowBright: Color;

/**
 * Apply bright blue background color
 * @param text - Text to apply background to
 * @returns String with bright blue background ANSI codes
 */
const bgBlueBright: Color;

/**
 * Apply bright magenta background color
 * @param text - Text to apply background to
 * @returns String with bright magenta background ANSI codes
 */
const bgMagentaBright: Color;

/**
 * Apply bright cyan background color
 * @param text - Text to apply background to
 * @returns String with bright cyan background ANSI codes
 */
const bgCyanBright: Color;

/**
 * Apply bright white background color
 * @param text - Text to apply background to
 * @returns String with bright white background ANSI codes
 */
const bgWhiteBright: Color;

Types

/**
 * Color function type - all color and styling functions follow this signature
 * @param text - String or number to style (numbers are converted to strings)
 * @returns Styled string with ANSI codes (when colors supported) or plain string
 */
type Color = (text: string | number) => string;

Environment Configuration

Colorette supports several environment variables and CLI flags for controlling color output:

  • Environment Variables:

    • NO_COLOR - Disable colors when set (any value)
    • FORCE_COLOR - Force colors when set (any value)
    • CI - Detected CI environments enable colors automatically (GitHub Actions, GitLab CI, CircleCI)
    • TERM - Terminal type detection (avoids "dumb" terminals)

  • CLI Flags:

    • --no-color - Disable colors
    • --color - Force colors

  • Programmatic Override:

    • Use createColors({ useColor: boolean }) to override detection

Input Handling

All color functions accept both strings and numbers as input:

  • String inputs: Processed directly with ANSI codes applied
  • Number inputs: Automatically converted to strings before processing
  • Empty/undefined inputs: Return empty string without throwing errors
  • Nested color sequences: Automatically handled with bleeding prevention to maintain proper formatting

Performance Characteristics

Colorette achieves high performance through several optimizations:

  • Lazy evaluation: Color functions are created once and reused
  • Efficient string operations: Uses substring() and indexOf() for minimal memory allocation
  • Bleeding prevention algorithm: Recursive replaceClose() function handles nested sequences without string rebuilding
  • Minimal overhead: When colors are disabled, functions return the String constructor for zero processing cost

docs

index.md

tile.json