CLI Tableau

2.0.1 · active · verified Wed Apr 22

cli-tableau is a robust JavaScript library designed for rendering pretty, highly customizable tables in command-line interfaces using Unicode characters. It offers extensive control over table structure, including options for horizontal, vertical, and cross-table layouts, and allows for detailed customization of borders, column widths, and styling characters. The current stable version, 2.0.1, indicates a mature codebase. Its release cadence appears to be relatively slow, focusing on stability. A key differentiator is its granular control over the `chars` property, enabling developers to define every single line and intersection character, from full Unicode borders to completely invisible separators, offering unparalleled flexibility in visual output compared to simpler table rendering utilities. It is primarily used within Node.js environments for CLI tools.

Common errors

```
TypeError: Table is not a constructor
```
cause Attempting to use `Table` as a constructor after an incorrect ES module named import (e.g., `import { Table } from 'cli-tableau';`), or if `require` returned an unexpected value.

fix Ensure you are using the CommonJS `const Table = require('cli-tableau');` pattern, as the library exports its main constructor as the default CommonJS export.
```
Cannot read properties of undefined (reading 'push')
```
cause This typically occurs if the `table` instance was not correctly created, often due to an issue with the `Table` constructor call, or if `Table` itself was `undefined` (e.g., from a failed import).

fix Verify that `require('cli-tableau')` successfully returned the Table constructor and that `new Table()` was called correctly. Check for typos in the import path or symbol, and ensure the module loaded as expected.

Warnings

gotcha cli-tableau is predominantly a CommonJS (CJS) library. While it works seamlessly in Node.js CJS projects, direct ES module (ESM) `import` statements may require specific Node.js configurations, bundler setups, or a CJS wrapper to function correctly in pure ESM projects. Consider using `createRequire` if mixing CJS into ESM.
Fix: For ESM projects, you might need `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const Table = require('cli-tableau');` or configure your bundler to handle CJS modules.
gotcha Custom character styles (`chars`) are powerful but can lead to unexpected visual output if not all necessary characters are defined or if they conflict with `borders` and `style` settings. Setting certain `chars` properties to empty strings will remove corresponding lines or intersections.
Fix: Always test your custom `chars` configuration with various data inputs. Refer to the documentation examples for common patterns, such as removing horizontal lines between rows by clearing `mid`, `left-mid`, `mid-mid`, `right-mid`.

Install

npm install cli-tableau npm
yarn add cli-tableau yarn
pnpm add cli-tableau pnpm

Imports

Table
wrong:
```
import Table from 'cli-tableau';
```
correct:
```
const Table = require('cli-tableau');
```
cli-tableau is primarily a CommonJS module. Direct ES module imports may not work without a CommonJS wrapper or bundler configuration, or specific Node.js settings.
Table (named import - incorrect)
wrong:
```
import { Table } from 'cli-tableau';
```
correct:
```
const Table = require('cli-tableau'); // Only a default export
```
The library exports a default constructor function, not named exports. Attempting a named import like `{ Table }` will result in `Table` being `undefined` in ES modules.

Quickstart

Demonstrates creating a basic horizontal table with custom headers, column widths, and basic styling, then populating it with data rows for console output.

const Table = require('cli-tableau');

const table = new Table({
    head: ['Task Description', 'Status', 'Due Date'],
    colWidths: [40, 15, 20],
    style: {
        'padding-left': 1,
        'padding-right': 1,
        'head': ['cyan'],
        'border': ['grey'],
        'compact': true // Makes rows more compact
    }
});

table.push(
    ['Implement feature X', 'In Progress', '2024-05-01'],
    ['Fix bug Y in module Z', 'Pending Review', '2024-04-28'],
    ['Write documentation for API V2', 'Not Started', '2024-05-15']
);

console.log(table.toString());

view raw JSON →