tessl/npm-kleur

The fastest Node.js library for formatting terminal text with ANSI colors

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Color Detection and Configuration

Name: tessl/npm-kleur
Author: tessl

Kleur automatically detects terminal color support and provides manual override capabilities. Both the main API and colors API share the same detection logic but use different configuration interfaces.

Automatic Detection

Kleur automatically detects color support based on environment variables and TTY context.

Detection Logic

// Pseudo-code for detection logic
const colorSupport = 
  !NODE_DISABLE_COLORS &&           // Not explicitly disabled
  NO_COLOR == null &&               // NO_COLOR not set
  TERM !== 'dumb' &&                // Not a dumb terminal
  (
    FORCE_COLOR != null &&          // FORCE_COLOR is set and not '0'
    FORCE_COLOR !== '0' ||
    isTTY                           // Or running in a TTY context
  );

Environment Variables

The following environment variables affect color detection:

FORCE_COLOR: Force enable colors (set to non-'0' value) or disable (set to '0')
NODE_DISABLE_COLORS: Disable colors when set to any value
NO_COLOR: Disable colors when set to any value (follows NO_COLOR standard)
TERM: Terminal type, colors disabled when set to 'dumb'

TTY Context

Colors are automatically disabled in non-TTY contexts such as:

Piped output (node app.js | grep error)
Redirected output (node app.js > log.txt)
Process spawning contexts

Manual Configuration

Override automatic detection for both APIs.

Main API Configuration

kleur.enabled: boolean;

Colors API Configuration

declare const $: { enabled: boolean };

Usage Examples

Environment Variable Control

# Force colors in piped output
FORCE_COLOR=1 node app.js > log.txt

# Disable colors explicitly
NODE_DISABLE_COLORS=1 node app.js

# Use NO_COLOR standard
NO_COLOR=1 node app.js

# Disable colors by setting FORCE_COLOR to '0'
FORCE_COLOR=0 node app.js

Manual Override - Main API

import kleur from "kleur";

// Check current state
console.log("Colors enabled:", kleur.enabled);

// Disable colors manually
kleur.enabled = false;
console.log(kleur.red("Won't be colored"));

// Re-enable colors
kleur.enabled = true;
console.log(kleur.red("Will be colored"));

// Conditional based on environment
kleur.enabled = process.env.NODE_ENV !== 'test';

// Use external color detection library
kleur.enabled = require('color-support').level > 0;

Manual Override - Colors API

import { $, red, green } from "kleur/colors";

// Check current state
console.log("Colors enabled:", $.enabled);

// Disable colors manually
$.enabled = false;
console.log(red("Won't be colored"));

// Re-enable colors
$.enabled = true;
console.log(red("Will be colored"));

// Conditional based on environment
$.enabled = process.env.NODE_ENV !== 'test';

// Use external color detection library
$.enabled = require('color-support').level > 0;

Runtime Detection Examples

import kleur from "kleur";

// Detect CI environments
if (process.env.CI) {
  kleur.enabled = process.env.FORCE_COLOR === '1';
}

// Detect specific terminals
if (process.env.TERM_PROGRAM === 'vscode') {
  kleur.enabled = true; // VS Code supports colors
}

// Detect Windows Command Prompt
if (process.platform === 'win32' && !process.env.CI) {
  kleur.enabled = process.stdout.isTTY;
}

// Progressive enhancement
function setupColors() {
  // Start with automatic detection
  const autoDetected = kleur.enabled;
  
  // Override for known environments
  if (process.env.NODE_ENV === 'test') {
    kleur.enabled = false;
  } else if (process.env.DEBUG) {
    kleur.enabled = true; // Always show colors in debug mode
  }
  
  console.log(`Colors: auto=${autoDetected}, final=${kleur.enabled}`);
}

Cross-Platform Compatibility

Windows Support

// Windows-specific considerations
if (process.platform === 'win32') {
  // Windows Terminal and modern terminals support colors
  // Legacy Command Prompt may have limited support
  const windowsColorSupport = 
    process.env.WT_SESSION ||              // Windows Terminal
    process.env.TERM_PROGRAM === 'vscode' || // VS Code terminal
    process.env.TERM === 'xterm-256color';   // Other modern terminals
    
  if (windowsColorSupport) {
    kleur.enabled = true;
  }
}

Unix/Linux Support

// Unix-like systems generally have good color support
if (process.platform !== 'win32') {
  // Most Unix terminals support colors
  // Check for specific terminal capabilities
  const colorTerms = ['xterm', 'xterm-color', 'xterm-256color', 'screen', 'screen-256color'];
  const supportsColor = colorTerms.some(term => process.env.TERM?.includes(term));
  
  if (supportsColor) {
    kleur.enabled = true;
  }
}

Docker and Container Support

// Container-specific detection
function detectContainerColors() {
  // Check for Docker environment
  if (process.env.DOCKER_CONTAINER) {
    // Colors work in Docker if TTY is available
    return process.stdout.isTTY;
  }
  
  // Check for other container runtimes
  if (process.env.KUBERNETES_SERVICE_HOST) {
    // Kubernetes pods may not have TTY
    return process.env.FORCE_COLOR === '1';
  }
  
  return kleur.enabled; // Use default detection
}

kleur.enabled = detectContainerColors();