CLI Boxes

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ...cli-boxes/index.js from ... not supported.

  cause `cli-boxes` version 4.0.0 and above is pure ESM, but your project is trying to import it using CommonJS `require()` syntax.
  fix Change your `require('cli-boxes')` statement to `import cliBoxes from 'cli-boxes';` and ensure your `package.json` has `"type": "module"` or your file uses the `.mjs` extension. Upgrade Node.js to version 18 or higher. If you cannot migrate to ESM, downgrade `cli-boxes` to version `3.x`.

• TypeError: Cannot read properties of undefined (reading 'vertical')

  cause You are attempting to access `vertical` or `horizontal` properties on a custom box definition using `cli-boxes` version 3.0.0 or higher.
  fix Update your custom box definitions to use the new property names: `left`, `right`, `top`, and `bottom` instead of `vertical` and `horizontal`.

• TypeError: Cannot read properties of undefined (reading 'single-double')

  cause You are trying to access a box style using its old, hyphenated name (e.g., 'single-double') with `cli-boxes` version 2.0.0 or higher.
  fix Use the camelCase equivalent for the box name, e.g., `cliBoxes.singleDouble` instead of `cliBoxes['single-double']`.

Warnings

• breaking Version 4.0.0 of `cli-boxes` is pure ESM (ECMAScript Modules) and requires Node.js 18 or higher. Projects using CommonJS or older Node.js versions must either remain on `cli-boxes@3.x` or refactor to use ESM.
  Fix: Migrate your project to use ES modules by setting `"type": "module"` in `package.json`, updating your `import` statements, and ensuring Node.js 18+ is installed. For CommonJS projects that cannot migrate, pin `cli-boxes` to a version lower than 4.0.0 (e.g., `^3.0.0`).
• breaking Version 3.0.0 introduced a change in the configuration keys for custom box definitions. The `vertical` and `horizontal` keys were renamed to `left`, `right`, `top`, and `bottom` respectively. This affects users providing custom box objects.
  Fix: Update any custom box definitions to use the new key names: `vertical` becomes `left` and `right`, `horizontal` becomes `top` and `bottom`. Refer to the diff provided in the v3.0.0 release notes.
• breaking Version 2.0.0 renamed two box styles: `single-double` became `singleDouble` and `double-single` became `doubleSingle`. Accessing the old hyphenated names will result in undefined values.
  Fix: Update your code to use the camelCase names `cliBoxes.singleDouble` and `cliBoxes.doubleSingle` instead of `cliBoxes['single-double']` and `cliBoxes['double-single']`.

Install

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

Imports

• cliBoxes
  wrong:

  const cliBoxes = require('cli-boxes');

  correct:

  import cliBoxes from 'cli-boxes';

  Since v4.0.0, cli-boxes is a pure ESM package and cannot be imported using CommonJS `require()`. Ensure your project is configured for ESM or use an older version.
• cliBoxes.single

  import cliBoxes from 'cli-boxes';
  const singleBox = cliBoxes.single;

  Access individual box definitions as properties of the default export. The structure of these objects changed in v3.0.0 for custom box definitions.
• Box

  import type { Box } from 'cli-boxes';

  While `cli-boxes` exports types, the primary usage often involves direct access to the `cliBoxes` object without explicitly importing its internal type definitions unless needed for custom type declarations.

Quickstart

Demonstrates importing the `cli-boxes` module, accessing the character definitions for the 'single' and 'double' box styles, and a simple example of how to use them to print a basic box in the terminal.

import cliBoxes from 'cli-boxes';

// Log the character definitions for the 'single' box style
console.log(cliBoxes.single);
/*
{
	topLeft: '┌',
	top: '─',
	topRight: '┐',
	right: '│',
	bottomRight: '┘',
	bottom: '─',
	bottomLeft: '└',
	left: '│'
}
*/

// You can use these characters to construct a box
const { topLeft, top, topRight, left, right, bottomLeft, bottom, bottomRight } = cliBoxes.double;
console.log(topLeft + top.repeat(5) + topRight);
console.log(left + ' Hello ' + right);
console.log(bottomLeft + bottom.repeat(5) + bottomRight);