ANSI Fragments for CLI Styling

0.2.1 verified Wed Apr 22 auth: no javascript

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.

Common errors

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

cause 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.

error TypeError: fragment.build is not a function ↓

cause 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().

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

cause 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.

Warnings

gotcha As 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.

gotcha All 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.

gotcha The 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.

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.

Install

npm install ansi-fragments

yarn add ansi-fragments

pnpm add ansi-fragments

Imports

color

wrong

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

correct

import { color } from 'ansi-fragments';

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

modifier

wrong

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

correct

import { modifier } from 'ansi-fragments';

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

container

wrong

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

correct

import { container } from 'ansi-fragments';

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

Quickstart

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);