{"id":16972,"library":"cli-width","title":"CLI Width Utility","description":"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.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/knownasilya/cli-width","tags":["javascript","typescript"],"install":[{"cmd":"npm install cli-width","lang":"bash","label":"npm"},{"cmd":"yarn add cli-width","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-width","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports the `cliWidth` function as its default export. While TypeScript might sometimes allow named import, the intended usage is a default import.","wrong":"import { cliWidth } from 'cli-width';","symbol":"cliWidth","correct":"import cliWidth from 'cli-width';"},{"note":"This is the standard CommonJS `require` syntax for Node.js environments. The package is compatible with both CJS and ESM.","symbol":"cliWidth (CommonJS)","correct":"const cliWidth = require('cli-width');"},{"note":"For type-only imports in TypeScript, use `import type` to ensure no runtime code is generated.","symbol":"Options type","correct":"import type { Options } from 'cli-width';"}],"quickstart":{"code":"import cliWidth, { Options } from 'cli-width';\nimport * as process from 'process';\n\n// Get the current CLI width with default fallbacks\nconst currentWidth = cliWidth();\nconsole.log(`Current CLI width: ${currentWidth}`);\n\n// Define custom options for fallback behavior\nconst customOptions: Options = {\n  defaultWidth: process.env.DEFAULT_CLI_WIDTH ? parseInt(process.env.DEFAULT_CLI_WIDTH, 10) : 80,\n  output: process.stdout,\n  tty: require('tty'), // Use the built-in tty module\n};\n\n// Get CLI width with custom options\nconst customWidth = cliWidth(customOptions);\nconsole.log(`CLI width with custom options: ${customWidth}`);\n\n// Example of setting an environment variable to test CLI_WIDTH fallback\nprocess.env.CLI_WIDTH = '120';\nconst envVarWidth = cliWidth();\nconsole.log(`CLI width with CLI_WIDTH env var: ${envVarWidth}`);\n\n// Clean up environment variable for subsequent tests\ndelete process.env.CLI_WIDTH;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Refactor calls to `cliWidth()` to pass an object literal for options: `cliWidth({ defaultWidth: 80, output: process.stderr })`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change `import { cliWidth } from 'cli-width';` to `import cliWidth from 'cli-width';` or `const cliWidth = require('cli-width');`.","cause":"Attempting to call `cliWidth` after importing it incorrectly using named import syntax when it's a default export.","error":"TypeError: cliWidth is not a function"},{"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.","cause":"Using `require('cli-width')` in an ECMAScript Module (ESM) file without proper configuration or transpilation.","error":"ReferenceError: require is not defined (in ESM context)"}],"ecosystem":"npm","meta_description":null}