cli-truncate

library6.0.0jsnpmunverified

cli-truncate is a JavaScript library designed for precisely truncating strings within a terminal environment, correctly accounting for the visual width occupied by characters, including those with ANSI escape codes (like colors and styles), Unicode surrogate pairs, and fullwidth characters. The current stable version is 6.0.0, which requires Node.js 22.x or later. The package has a consistent release cadence, often introducing new major versions to align with updated Node.js engine requirements, alongside minor and patch releases for bug fixes and feature enhancements. Its key differentiators lie in its robust handling of terminal-specific challenges: it ensures that styled text, such as output from `chalk`, is truncated accurately without breaking formatting, and it correctly measures the width of complex Unicode characters that standard `String.prototype.slice` or similar methods would misinterpret. It offers flexible truncation positions (start, middle, end) and options like `space` for adding a gap before the ellipsis and `preferTruncationOnSpace` to attempt truncation at a word boundary for better readability.

serialization

npm install cli-truncate

github ↗package ↗

INSTALL

IMPORT

SIG · CLI-TRUNCATE

cli-truncate

serializationjavascriptv6.0.0

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.

cliTruncate

✓ import cliTruncate from 'cli-truncate';

✗ const cliTruncate = require('cli-truncate');

The package has been pure ESM since v3.0.0. CommonJS `require()` is not supported.

cliTruncate (TypeScript)

✓ import cliTruncate from 'cli-truncate';

TypeScript types are included and automatically picked up when importing.

Options (TypeScript Type)

✓ import type { Options } from 'cli-truncate';

For type-only imports in TypeScript, use the `import type` syntax.

Demonstrates truncating a long paragraph to the current terminal width, gracefully handling character widths and potential ANSI escape codes, for clean console output. It also shows using `preferTruncationOnSpace` for better readability.

import cliTruncate from 'cli-truncate'; const paragraph = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.'; // Truncate a long string to the current terminal width, or 80 columns if not available. const terminalWidth = process.stdout.columns ?? 80; const truncatedText = cliTruncate(paragraph, terminalWidth, { position: 'end', preferTruncationOnSpace: true }); console.log('Original length:', paragraph.length); console.log('Truncated length (visual):', truncatedText.length); console.log('Truncated text:', truncatedText);

Debug

Known issues

breakingNode.js 22 or later is now required for `cli-truncate` v6.0.0.

fix

Upgrade your Node.js environment to version 22 or higher, or downgrade `cli-truncate` to a compatible major version (e.g., v5 for Node.js 20, v4 for Node.js 18).

affects: >=6.0.0

breaking`cli-truncate` migrated to pure ESM (ECMAScript Modules). CommonJS `require()` is no longer supported.

fix

Update your import statements from `const cliTruncate = require('cli-truncate');` to `import cliTruncate from 'cli-truncate';`. Ensure your project is configured for ESM, potentially by adding `'type': 'module'` to your `package.json` or by using `.mjs` file extensions.

affects: >=3.0.0

breakingNode.js 20 or later is required for `cli-truncate` v5.0.0.

fix

Upgrade your Node.js environment to version 20 or higher, or downgrade `cli-truncate` to v4 if you need Node.js 18 support.

affects: >=5.0.0 <6.0.0

breakingNode.js 18 or later is required for `cli-truncate` v4.0.0.

fix

Upgrade your Node.js environment to version 18 or higher, or downgrade `cli-truncate` to v3 if you need Node.js 12.20+ support.

affects: >=4.0.0 <5.0.0

gotchaWhen using ANSI escape codes (e.g., with `chalk`), `cli-truncate` attempts to inherit the style for the truncation character. For `position: 'middle'`, the truncation character does not inherit surrounding ANSI styles.

fix

Be aware of this specific styling behavior if precise style continuity for the ellipsis in `position: 'middle'` is critical to your output design.

affects: >=5.1.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/cli-truncate/index.js from /your/project/file.js not supported.

Attempting to use `require()` to import `cli-truncate`, which is an ES Module.

fix

Change your import statement to `import cliTruncate from 'cli-truncate';`. Ensure your `package.json` has `'type': 'module'` or use `.mjs` file extension for your source file.

The 'cli-truncate' package is not compatible with your current Node.js version. Required: '>=22'

Running `cli-truncate` v6.0.0 (or a similar version) with an older Node.js runtime.

fix

Upgrade your Node.js installation to version 22 or higher. Alternatively, install an older major version of `cli-truncate` that is compatible with your current Node.js version (e.g., `npm install cli-truncate@5` for Node.js 20).

Upgrade

Version history

6.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/sindresorhus/cli-truncate ↗

packagehttps://www.npmjs.com/package/cli-truncate ↗