ANSI Fragments for CLI Styling

Common errors

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

• 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()`.

• 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 npm
• yarn add ansi-fragments yarn
• pnpm add ansi-fragments pnpm

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