ansi-to-html

ansi-to-html is a small, focused Node.js library that turns raw ANSI-escaped terminal output — the kind produced by colored console logs, CI build output, or git log — into semantically equivalent HTML markup. It ships a Filter class with a single toHtml() method, so any tool that captures terminal output (a log viewer, a CI dashboard, a build-status page) can render it in a browser with the original colors, bold/underline/strike styling, and 256-color/truecolor support preserved.

Beyond the library API, the package installs an ansi-to-html CLI binary that reads from a file or stdin and streams converted HTML to stdout, making it usable directly in shell pipelines (git log | ansi-to-html > log.html). It originated as a JavaScript port of a Ruby ANSI-to-HTML converter from the bcat project and has been maintained and extended by the community since 2012.

What You Get

• A Filter class (new Convert(options)) with a toHtml(input) method that accepts a string or array of strings and returns HTML
• Full ANSI SGR support: 16-color and 256-color (xterm) foreground/background, 24-bit RGB truecolor, bold, italic, underline, strikethrough, and blink
• A stream: true option that keeps style state ‘sticky’ across successive toHtml() calls for chunked/streamed input
• An escapeXML option to HTML/XML-entity-escape the plain text portions of the output
• A CLI binary (ansi-to-html) that reads a file or stdin and streams converted HTML to stdout, for use directly in shell pipelines
• Configurable default/reset foreground and background colors, and a colors option to override individual palette entries or the entire 256-color table

Common Use Cases

• Rendering colored CI/CD build logs in a web-based dashboard
• Displaying git log, linter, or test-runner output with its original terminal coloring inside a browser-based UI
• Building log-viewer or terminal-recording playback tools that need to preserve ANSI color/style information as HTML
• Piping colorized CLI output into a static HTML file for sharing or archiving
• Embedding live streamed terminal output (e.g. from a WebSocket-connected process) into a web page with correct styling

Under The Hood

Architecture The entire library is a single module (lib/ansi_to_html.js) built around a regex-driven tokenizer (tokenize()) and a small state machine. The tokenizer walks the input string against an ordered list of regex patterns — for backspaces, ANSI SGR sequences, 256-color and RGB escape codes, and CR/LF handling — replacing each match with an empty string and invoking a callback with a (token, data) pair as it goes. generateOutput() dispatches on the token type (text, display, xterm256Foreground, xterm256Background, rgb) to push or close HTML tags onto a stack array, which the Filter class flushes into a joined HTML string in toHtml(). When the stream option is set, an additional stickyStack — deduplicated by ANSI “category” (bold, underline, foreground-color, etc.) — carries open styles across separate toHtml() invocations, letting the converter be fed a stream in chunks (as the CLI’s htmlStream() does) rather than a single flat string. There is no dependency injection or multi-layer architecture; the design trades structure for a compact, single-purpose implementation, so the main risk if the core token grammar changes is that the ordered regex list and its short-circuiting logic (ansiHandler/ansiMatch) would need careful re-verification.

Tech Stack The package is plain CommonJS JavaScript (no TypeScript compilation, though a hand-written lib/ansi_to_html.d.ts ships type declarations) targeting Node.js >=8. Its only runtime dependency is entities (^4.0.0), used solely for XML-entity encoding when escapeXML is enabled. Development tooling is mocha + chai for tests, nyc for coverage reporting (text + HTML reporters), and ESLint for linting, wired into a CircleCI pipeline (.circleci/config.yml). There is no bundler or build step — the published package is the raw lib/ and bin/ source.

Code Quality Tests live in test/ansi_to_html.js and test/cli.js, using mocha’s describe/it structure and chai’s expect assertions, with dozens of cases covering plain text, CR/LF variants, 16-color, 256-color, RGB, bold/italic/underline/strike, streaming mode, and CLI flag handling — a genuinely comprehensive suite for the surface area involved. Naming is consistent and functions are short and single-purpose, with JSDoc comments on most helper functions. There is no static type-checking (plain JS, not TypeScript), and the .d.ts file is maintained by hand rather than generated, so type accuracy depends on manual upkeep rather than compiler enforcement.

API Design The public surface is deliberately minimal: instantiate new Convert(options) once, then call .toHtml(text) as many times as needed. Options are a flat object (fg, bg, newline, escapeXML, stream, colors) with sensible defaults, so a caller can get correct output with zero configuration and opt into streaming or custom palettes incrementally. The CLI mirrors the same options as flags (-n, -x, -f, -b), keeping the two interfaces conceptually aligned. The main friction point for new users is that behavior nuances (e.g. how stream mode’s sticky-style tracking interacts with resets) are only discoverable by reading the source or tests, since the README documents options but not these interaction details.