cli-width

library4.1.0jsnpmunverified

cli-width is a JavaScript utility for Node.js environments that accurately determines the current width of the stdout window. It employs a robust fallback mechanism, checking `tty` information, `output.columns` property, a custom `CLI_WIDTH` environment variable, and finally a configurable default width. The package is currently stable at version 4.1.0 and is actively maintained, with releases occurring as needed for bug fixes or minor enhancements. It is designed to be lightweight and provides TypeScript types out-of-the-box, making it suitable for modern Node.js projects that require responsive command-line interfaces. Its primary differentiator is the comprehensive fallback strategy to ensure a width is always returned.

devops

npm install cli-width

github ↗package ↗

INSTALL

IMPORT

SIG · CLI-WIDTH

cli-width

devopsjavascriptv4.1.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.

cliWidth

✓ import cliWidth from 'cli-width';

✗ import { cliWidth } from 'cli-width';

The package exports the `cliWidth` function as its default export. While TypeScript might sometimes allow named import, the intended usage is a default import.

cliWidth (CommonJS)

✓ const cliWidth = require('cli-width');

This is the standard CommonJS `require` syntax for Node.js environments. The package is compatible with both CJS and ESM.

Options type

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

For type-only imports in TypeScript, use `import type` to ensure no runtime code is generated.

This quickstart demonstrates how to get the CLI width with default settings, and how to configure it with custom options for default width, output stream, and tty module. It also shows how the `CLI_WIDTH` environment variable can influence the detected width.

import cliWidth, { Options } from 'cli-width'; import * as process from 'process'; // Get the current CLI width with default fallbacks const currentWidth = cliWidth(); console.log(`Current CLI width: ${currentWidth}`); // Define custom options for fallback behavior const customOptions: Options = { defaultWidth: process.env.DEFAULT_CLI_WIDTH ? parseInt(process.env.DEFAULT_CLI_WIDTH, 10) : 80, output: process.stdout, tty: require('tty'), // Use the built-in tty module }; // Get CLI width with custom options const customWidth = cliWidth(customOptions); console.log(`CLI width with custom options: ${customWidth}`); // Example of setting an environment variable to test CLI_WIDTH fallback process.env.CLI_WIDTH = '120'; const envVarWidth = cliWidth(); console.log(`CLI width with CLI_WIDTH env var: ${envVarWidth}`); // Clean up environment variable for subsequent tests delete process.env.CLI_WIDTH;

Debug

Known issues

breakingThe way options are passed to `cliWidth` changed significantly in v2.0.0. Previously, options might have been positional or less structured. Now, all configuration must be passed via a single `options` object as the first argument.

fix

Refactor calls to `cliWidth()` to pass an object literal for options: `cliWidth({ defaultWidth: 80, output: process.stderr })`.

affects: >=2.0.0

gotchaWhen running in non-TTY environments (e.g., piped output, CI/CD without TTY emulation), `cli-width` might return the `defaultWidth` or `0` if not explicitly configured. This is expected behavior as there's no terminal to query for dimensions.

fix

Always provide a sensible `defaultWidth` in your options if a non-zero width is critical for your application in all environments: `cliWidth({ defaultWidth: 80 })`. You can also set the `CLI_WIDTH` environment variable.

affects: >=1.0.0

gotchaThe `tty` module fallback relies on `require('tty')`. In environments where the `tty` module is not available or behaves unexpectedly (e.g., some browser bundlers trying to shim Node built-ins), this fallback might fail. Ensure your target environment is Node.js.

fix

This package is intended for Node.js environments. If bundling for a browser, consider conditional imports or a browser-specific alternative for width detection. For Node.js, ensure `tty` is resolvable.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: cliWidth is not a function

Attempting to call `cliWidth` after importing it incorrectly using named import syntax when it's a default export.

fix

Change `import { cliWidth } from 'cli-width';` to `import cliWidth from 'cli-width';` or `const cliWidth = require('cli-width');`.

ReferenceError: require is not defined (in ESM context)

Using `require('cli-width')` in an ECMAScript Module (ESM) file without proper configuration or transpilation.

fix

If your project is configured for ESM (e.g., `"type": "module"` in `package.json`), use `import cliWidth from 'cli-width';`. If you need to use `require` in an ESM file, consider dynamic `import()` or review your build setup.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/knownasilya/cli-width ↗

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