console-grid

library2.2.4jsnpmunverified

console-grid is a lightweight, zero-dependency utility for Node.js environments, designed to render highly customizable and formatted tables and grids directly in the console. Currently at version 2.2.4, it provides robust features such as tree-style rows for hierarchical data, precise column alignment (left, center, right), custom padding, and multi-line headers with automatic word wrapping. A key differentiator is its comprehensive support for colorful cells using ANSI escape codes, full Unicode character handling (including CJK and Emojis), and custom character width calculation via a `getCharLength` option. It offers dual support for both ESM and CommonJS modules and ships with TypeScript type definitions, making it suitable for modern JavaScript and TypeScript projects. While a specific release cadence isn't explicitly published, its stable nature as a core utility suggests infrequent but well-tested updates.

serialization

npm install console-grid

github ↗package ↗

INSTALL

IMPORT

SIG · CONSOLE-GRID

console-grid

serializationjavascriptv2.2.4

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.

✓ import CG from 'console-grid';

✗ import { CG } from 'console-grid';

CG is the default function export for rendering grids, available in both ESM and CJS.

ConsoleGrid

✓ import { ConsoleGrid } from 'console-grid';

✗ const ConsoleGrid = require('console-grid').ConsoleGrid;

ConsoleGrid is a named class export, exclusively available via ESM imports since v2.x. It is not directly exposed through CommonJS require.

✓ const CG = require('console-grid');

✗ const { ConsoleGrid } = require('console-grid');

For CommonJS, the default export CG (the grid rendering function) is the primary way to interact with the library.

Demonstrates basic grid rendering, customizing header visibility, and configuring column widths, including support for multi-line headers.

import CG from 'console-grid'; // Example 1: Basic grid rendering console.log('--- Basic Grid ---'); CG({ columns: ['', 'Name', 'Value'], rows: [ [1, 'Tom', 'Value 1'], [2, 'Jerry', 'Value 2'] ] }); // Example 2: Grid without header console.log('\n--- Grid Without Header ---'); CG({ options: { headerVisible: false }, columns: ['', 'Name', 'Value'], rows: [ [1, 'Tom', 'Value 1'], [2, 'Jerry', 'Value 2'] ] }); // Example 3: Grid with column width constraints and multi-line header console.log('\n--- Grid with Column Widths and Multi-Line Header ---'); CG({ columns: [ '', { name: 'Name', minWidth: 15 }, { name: 'Value', maxWidth: 20 }, { name: 'Multiple Line Header', maxWidth: 15 } ], rows: [ [1, 'Hello', 'Long Text Value', 'Long Text Value'], [2, 'Hello There', 'Long Text Value Long Text Value', 'Long Text Value Long Text Value'] ] });

Debug

Known issues

gotchaWhen using ESM, the primary grid rendering function is the default export (CG), while the ConsoleGrid class is a named export. Importing `CG` as a named export (`import { CG } from 'console-grid';`) will result in a runtime error.

fix

Always use `import CG from 'console-grid';` for the default function in ESM, or `const CG = require('console-grid');` for CommonJS.

affects: >=2.0.0

gotchaAttempting to access the `ConsoleGrid` class via CommonJS `require` (e.g., `require('console-grid').ConsoleGrid`) will result in `undefined` or a runtime error, as it's only exported as a named ESM export.

fix

If you require the `ConsoleGrid` class, your project must use ESM and import it with `import { ConsoleGrid } from 'console-grid';`.

affects: >=2.0.0

gotchaTable rendering may appear garbled, misaligned, or have incorrect column widths in certain terminal environments, especially when dealing with complex Unicode characters (e.g., CJK, emojis) or ANSI escape codes.

fix

Ensure your terminal supports full Unicode and ANSI escape codes. For specific character width issues, utilize the `getCharLength` option to provide a custom character width calculation function in the grid options.

affects: >=1.0.0

gotchaWhile `console-grid` supports ANSI escape codes for colorful cells, improper use (e.g., unbalanced codes, unsupported sequences) can lead to unexpected rendering issues or terminal state corruption.

fix

Always ensure ANSI escape codes are correctly formed and balanced. For debugging, try rendering the grid with `colorful: false` in the options to isolate the issue to color codes.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: CG is not a function

In ESM, the default export `CG` was imported as a named export.

fix

Change the import statement from `import { CG } from 'console-grid';` to `import CG from 'console-grid';`.

TypeError: Cannot destructure property 'ConsoleGrid' of 'require(...)' as it is undefined.

Attempting to access the `ConsoleGrid` class using CommonJS `require()` syntax, but it is only exposed as a named ESM export.

fix

If you need the `ConsoleGrid` class, convert your file to an ESM module (`.mjs` extension or `"type": "module"` in `package.json`) and use `import { ConsoleGrid } from 'console-grid';`.

ERR_REQUIRE_ESM

You are attempting to `require()` this package in a Node.js project configured as a pure ESM module, which prevents `require` calls.

fix

If `console-grid` is dual-packaged, ensure your project's `package.json` does not have `"type": "module"` if you intend to use `require()`. Otherwise, use `import CG from 'console-grid';` for ESM imports.

Upgrade

Version history

2.2.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/cenfun/console-grid ↗

packagehttps://www.npmjs.com/package/console-grid ↗