{"id":17416,"library":"ansi-fragments","title":"ANSI Fragments for CLI Styling","description":"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.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/zamotany/ansi-fragments","tags":["javascript","cli","ansi"],"install":[{"cmd":"npm install ansi-fragments","lang":"bash","label":"npm"},{"cmd":"yarn add ansi-fragments","lang":"bash","label":"yarn"},{"cmd":"pnpm add ansi-fragments","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ansi-fragments is an ESM-only module. CommonJS require() is not supported.","wrong":"const { color } = require('ansi-fragments');","symbol":"color","correct":"import { color } from 'ansi-fragments';"},{"note":"ansi-fragments is an ESM-only module. CommonJS require() is not supported.","wrong":"const { modifier } = require('ansi-fragments');","symbol":"modifier","correct":"import { modifier } from 'ansi-fragments';"},{"note":"Destructuring is the standard way to import named exports from this ESM module.","wrong":"const container = require('ansi-fragments').container;","symbol":"container","correct":"import { container } from 'ansi-fragments';"}],"quickstart":{"code":"import { color, modifier, pad, container, fixed, ifElse } from 'ansi-fragments';\n\nconst generateLogMessage = (level, message, timestamp, hasError) => {\n  const levelFragment = ifElse(\n    () => hasError,\n    color('red', modifier('bold', level.toUpperCase())),\n    color('green', modifier('italic', level))\n  );\n\n  const timeFragment = color('gray', `[${timestamp}]`);\n\n  const paddedMessage = container(\n    fixed(8, 'start', levelFragment),\n    pad(1),\n    timeFragment,\n    pad(1),\n    message\n  );\n\n  return paddedMessage.build();\n};\n\nconst now = new Date().toISOString().slice(11, 19);\n\nconsole.log(generateLogMessage('success', 'Operation completed successfully!', now, false));\nconsole.log(generateLogMessage('warning', 'Cache might be stale.', now, false));\nconsole.log(generateLogMessage('error', 'Failed to connect to database.', now, true));\nconsole.log(generateLogMessage('info', 'Processing batch job...', now, false));\n// Simulate a long message being truncated by fixed()\nconsole.log(generateLogMessage('debug', 'This is a very long debug message that should be truncated.', now, false));\n\n// Example without fixed, just showing container and colors\nconst header = container(\n  color('cyan', '📦 Package Installer'),\n  pad(1, '-'),\n  color('magenta', 'v1.2.3')\n).build();\nconsole.log(header);\n","lang":"javascript","description":"Demonstrates creating complex, conditional, and fixed-width CLI log messages using various ansi-fragments builders like color, modifier, container, fixed, and ifElse."},"warnings":[{"fix":"Always consult the project's changelog or release notes before updating minor versions. Pin exact versions for production use if stability is critical.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For advanced color requirements, consider alternative CLI styling libraries or implement custom ANSI escape code sequences if direct control is needed.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"`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.","severity":"breaking","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"This typically occurs when attempting to use named ESM imports in a CommonJS context or due to incorrect bundler configuration.","error":"TypeError: (0, _ansi_fragments.color) is not a function"},{"fix":"Always call `.build()` at the end of your fragment chain or container to obtain the final ANSI-formatted string. For example, `container(...).build()`.","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.","error":"TypeError: fragment.build is not a function"},{"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.","cause":"The package is either not installed in your project, or there is a typo in the import path.","error":"Module not found: Error: Can't resolve 'ansi-fragments'"}],"ecosystem":"npm","meta_description":null}