@stackline/ansicolors

Zero-dependency ANSI color wrappers with exact ansicolors compatibility and first-party types.

Documentation | npm | Issues | Repository

Current package version: 1.0.4

Why this package?

Zero-dependency ANSI foreground and background color wrappers. This package is a compatibility-first, independently maintained fork of ansicolors@0.3.2, with accurate first-party types and current CommonJS, ESM, and browser distribution.

Stackline maintains this package independently. The original author does not endorse this fork.

Compatibility

Version 1.x preserves the observable ansicolors@0.3.2 runtime contract:

• all 32 method names and ANSI sequences;
• exact string wrapping and JavaScript coercion behavior;
• nested foreground/background byte order;
• open and close maps;
• method extraction and object property behavior;
• CommonJS default object;
• zero runtime dependencies.

The package intentionally does not add bold, italic, underline, terminal detection, color disabling, stripping, or nesting repair to the historical methods. Use a full terminal styling library when those features are required.

Installation

Install

npm install @stackline/ansicolors

Existing projects can keep the package key and every require('ansicolors') call unchanged:

npm install ansicolors@npm:@stackline/ansicolors@^1.0.2

Usage

const colors = require('@stackline/ansicolors')

console.log(colors.red('failed'))
console.log(colors.bgGreen(colors.black('passed')))

Native ESM supports both default and named imports:

import colors, { bgBlue, brightWhite } from '@stackline/ansicolors'

console.log(bgBlue(brightWhite('ready')))
console.log(colors.green('connected'))

Features and Integrations

TypeScript

Declarations ship with the package and are tested with TypeScript 3.9 and the current compiler. Do not install @types/ansicolors for the scoped package.

The first-party declarations reflect runtime precisely: color properties are functions, while open and close properties are strings. This corrects the recursive callable shape exposed by the separate historical declaration package.

Browser

Package export conditions select self-contained browser builds for bundlers. Standalone artifacts are also available:

• dist/ansicolors.browser.mjs
• dist/ansicolors.browser.cjs
• dist/ansicolors.global.js, exposing AnsiColors

Migration

See MIGRATION.md for direct, alias, CommonJS, ESM, and TypeScript migration notes.

Security

See SECURITY.md. No runtime CVE or GHSA is claimed for upstream ansicolors; this fork focuses on maintenance continuity, type correctness, distribution quality, and reproducible compatibility.

API Surface

API

Foreground methods:

black blue cyan green magenta red white yellow
brightBlack brightBlue brightCyan brightGreen
brightMagenta brightRed brightWhite brightYellow

Background methods use the same names with a bg prefix:

bgBlack bgBlue bgCyan bgGreen bgMagenta bgRed bgWhite bgYellow
bgBrightBlack bgBrightBlue bgBrightCyan bgBrightGreen
bgBrightMagenta bgBrightRed bgBrightWhite bgBrightYellow

Every method surrounds its input with one opening SGR sequence and the historical foreground (39m) or background (49m) reset.

Escape Codes

Opening and closing sequences remain directly available as strings:

colors.open.blue       // '\u001b[34m'
colors.close.blue      // '\u001b[39m'
colors.open.bgYellow   // '\u001b[43m'
colors.close.bgYellow  // '\u001b[49m'

Local Development

git clone https://github.com/alexandroit/stackline-ansicolors.git
cd stackline-ansicolors
npm ci
npm run verify

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:smoke

Release Checklist

Verification

Release gates include the complete upstream suite, a full 32-color matrix, differential execution against official 0.3.2, coercion and object-contract tests, 100% core coverage, TypeScript 3.9/current compilation, CJS/ESM/browser checks, packed installation, package metadata linting, production audit, npm alias installation, and the complete cardinal@2.1.1 downstream suite.

Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

License And Attribution

MIT. See LICENSE and NOTICE. Original work copyright 2013 Thorsten Lorenz.

Credits and original authors

• Original project: ansicolors.
• Stackline Maintainers.
• Thorsten Lorenz.
• Copyright 2013 Thorsten Lorenz.
• Original work copyright 2013 Thorsten Lorenz.
• Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

• Stackline website
• GitHub projects
• npm packages
• Reddit community — r/Stackline
• Maintainer LinkedIn

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.