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.
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-colorette@2.0.0index.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
- Use
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()andindexOf()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
Stringconstructor for zero processing cost