{"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,"search_vec":"'0.2.1':32 'adopt':34 'aesthet':17 'allow':41 'ansi':1,7,26,87,116,135 'ansi-encod':86 'ansi-frag':6 'approach':40 'build':73,76 'builder':38 'builder-pattern':37 'cadenc':119 'cli':4,23,105,134 'code':28 'color':54 'command':20 'command-lin':19 'compact':11 'compos':44 'construct':16 'contain':56 'convert':79 'core':67 'current':29 'design':14 'develop':42 'differenti':68 'dx':102 'earli':131 'encapsul':63 'encod':88 'escap':27 'exhaust':111 'explicit':71 'featur':117 'fix':58 'focus':96 'fragment':2,8,47,72,81 'function':52 'ifels':59 'infrequ':121 'interfac':22 'javascript':12,133 'librari':13,50,128 'like':53 'line':21 'list':112 'log':106 'logic':65 'method':77 'micro':126 'micro-util':125 'modifi':55 'new':93 'nice':101 'offer':109 'output':24 'pad':57 'pattern':39 'pleas':18 'possibl':115 'programmat':48 'project':94 'provid':51,61,99 'rather':107 'relat':92 'releas':118 'singl':85 'stage':132 'string':89 'structur':104 'style':5,45,64 'text':46 'tree':82 'typic':122 'uniqu':36 'use':25 'util':127 'version':31","created_at":"2026-04-22T17:41:37.202101+00:00","updated_at":"2026-04-22T17:41:37.202101+00:00","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,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/zamotany/ansi-fragments","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/ansi-fragments","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-21","install_tag":null}}