Registry / http-networking / ansi-fragments

ansi-fragments

library0.2.1jsnpmunverified

ansi-fragments is a compact JavaScript library designed for constructing aesthetically pleasing command-line interface (CLI) outputs using ANSI escape codes. Currently at version 0.2.1, it adopts a unique builder-pattern approach, allowing developers to compose styled text fragments programmatically. The library provides functions like `color`, `modifier`, `container`, `pad`, `fixed`, `ifElse`, and `provide` to encapsulate styling logic. Its core differentiator is the explicit fragment building and the `.build()` method, which converts the fragment tree into a single ANSI-encoded string. While a relatively new project, its focus is on providing a 'nice DX' for structured CLI logging rather than offering an exhaustive list of all possible ANSI features. Release cadence is infrequent, typical for a micro-utility library in its early stages.

http-networking

npm install ansi-fragments

github ↗package ↗

INSTALL

IMPORT

SIG · ANSI-FRAGMENTS

ansi-fragments

http-networkingjavascriptv0.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

color

✓ import { color } from 'ansi-fragments';

✗ const { color } = require('ansi-fragments');

ansi-fragments is an ESM-only module. CommonJS require() is not supported.

modifier

✓ import { modifier } from 'ansi-fragments';

✗ const { modifier } = require('ansi-fragments');

ansi-fragments is an ESM-only module. CommonJS require() is not supported.

container

✓ import { container } from 'ansi-fragments';

✗ const container = require('ansi-fragments').container;

Destructuring is the standard way to import named exports from this ESM module.

Demonstrates creating complex, conditional, and fixed-width CLI log messages using various ansi-fragments builders like color, modifier, container, fixed, and ifElse.

import { color, modifier, pad, container, fixed, ifElse } from 'ansi-fragments'; const generateLogMessage = (level, message, timestamp, hasError) => { const levelFragment = ifElse( () => hasError, color('red', modifier('bold', level.toUpperCase())), color('green', modifier('italic', level)) ); const timeFragment = color('gray', `[${timestamp}]`); const paddedMessage = container( fixed(8, 'start', levelFragment), pad(1), timeFragment, pad(1), message ); return paddedMessage.build(); }; const now = new Date().toISOString().slice(11, 19); console.log(generateLogMessage('success', 'Operation completed successfully!', now, false)); console.log(generateLogMessage('warning', 'Cache might be stale.', now, false)); console.log(generateLogMessage('error', 'Failed to connect to database.', now, true)); console.log(generateLogMessage('info', 'Processing batch job...', now, false)); // Simulate a long message being truncated by fixed() console.log(generateLogMessage('debug', 'This is a very long debug message that should be truncated.', now, false)); // Example without fixed, just showing container and colors const header = container( color('cyan', '📦 Package Installer'), pad(1, '-'), color('magenta', 'v1.2.3') ).build(); console.log(header);

Debug

Known issues

gotchaAs a pre-1.0 library (version 0.2.1), `ansi-fragments` may introduce breaking changes in minor versions. Review changelogs carefully when upgrading to avoid unexpected issues.

fix

Always consult the project's changelog or release notes before updating minor versions. Pin exact versions for production use if stability is critical.

affects: <1.0.0

gotchaAll fragment trees must explicitly call the `.build()` method to render the final ANSI string. Forgetting this will result in an object being serialized to string (e.g., `[object Object]`) instead of the intended styled output.

fix

Ensure that the final fragment or container in your chain always has `.build()` appended to convert it into a printable string with ANSI escape codes.

affects: >=0.1.0

gotchaThe library primarily supports standard 8-color ANSI colors and common text modifiers. It does not provide built-in support for 256-color, true-color (RGB), or custom background/foreground color codes beyond the basic ANSI set.

fix

For advanced color requirements, consider alternative CLI styling libraries or implement custom ANSI escape code sequences if direct control is needed.

affects: >=0.1.0

breaking`ansi-fragments` is published as an ESM (ECMAScript Module) and expects to be imported using `import` statements. Attempting to `require()` it in CommonJS environments will lead to import errors.

fix

Ensure your project is configured for ESM (e.g., by setting `"type": "module"` in your `package.json` for Node.js projects) or use dynamic `import()` for compatibility in mixed environments.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: (0, _ansi_fragments.color) is not a function

This typically occurs when attempting to use named ESM imports in a CommonJS context or due to incorrect bundler configuration.

fix

Ensure your project is configured for ESM. For Node.js, set `"type": "module"` in your `package.json`. For bundlers, verify your configuration supports ESM output/resolution.

TypeError: fragment.build is not a function

This error indicates that the `.build()` method was not called on a fragment or container object, leading to it being treated as a generic object.

fix

Always call `.build()` at the end of your fragment chain or container to obtain the final ANSI-formatted string. For example, `container(...).build()`.

Module not found: Error: Can't resolve 'ansi-fragments'

The package is either not installed in your project, or there is a typo in the import path.

fix

Run `npm install ansi-fragments` or `yarn add ansi-fragments` to install the package. Double-check your `import` statement for any typos in the module name.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

38 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zamotany/ansi-fragments ↗

packagehttps://www.npmjs.com/package/ansi-fragments ↗