CLI Width Utility

Common errors

• TypeError: cliWidth is not a function

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

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

Warnings

• breaking The 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 })`.
• gotcha When 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.
• gotcha The `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.

Install

• npm install cli-width npm
• yarn add cli-width yarn
• pnpm add cli-width pnpm

Imports

• cliWidth
  wrong:

  import { cliWidth } from 'cli-width';

  correct:

  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.

Quickstart

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;