Registry / devops / blessed-contrib

blessed-contrib

library4.11.0jsnpmunverified

blessed-contrib is a JavaScript library designed for creating rich terminal dashboards and other console-based applications using ASCII/ANSI art. It extends the core `blessed` library, providing a suite of custom widgets such as line charts, bar charts, gauges, LCD displays, tables, and maps, some of which leverage `node-drawille` for advanced graphics. The current stable version is 4.11.0, with releases occurring irregularly, typically annually or semi-annually, focusing on stability. Its key differentiators include a comprehensive set of data visualization widgets tailored for the terminal, seamless integration with `blessed`'s powerful screen management, and explicit support across Linux, OS X, and Windows (with specific prerequisites for the latter). It aims to provide developer-friendly tools for creating visually engaging command-line interfaces.

devops

npm install blessed-contrib

github ↗package ↗

INSTALL

IMPORT

SIG · BLESSED-CONTRIB

blessed-contrib

devopsjavascriptv4.11.0

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.

contrib

✓ const contrib = require('blessed-contrib');

✗ import contrib from 'blessed-contrib';

blessed-contrib is primarily a CommonJS module. For modern TypeScript or ESM-only projects, `import * as contrib from 'blessed-contrib';` is often used, potentially requiring `esModuleInterop: true` in tsconfig or specific Node.js loader configuration.

Widget Constructors

✓ const lineWidget = contrib.line({ /* options */ });

✗ import { line } from 'blessed-contrib';

Widget constructors (e.g., `line`, `bar`, `gauge`) are properties of the main `contrib` object, not top-level named exports of the package.

blessed.screen()

✓ const blessed = require('blessed'); const screen = blessed.screen();

✗ import { screen } from 'blessed';

An instance of `blessed`'s `screen` is fundamental for all `blessed-contrib` widgets. `blessed` itself is also a CommonJS package and requires the `require()` syntax.

This example sets up a `blessed` screen, uses `blessed-contrib`'s grid layout, and displays a line chart and a bar chart with sample data. It also includes essential keybindings for graceful exit.

import blessed from 'blessed'; import contrib from 'blessed-contrib'; const screen = blessed.screen({ smartCSR: true, title: 'blessed-contrib Demo' }); const grid = new contrib.grid({ rows: 12, cols: 12, screen: screen }); const line = grid.set(0, 0, 6, 6, contrib.line, { style: { line: 'yellow', text: 'green', baseline: 'black' }, xLabelPadding: 3, xPadding: 5, label: 'CPU Usage', showLegend: true }); const data = { x: ['t1', 't2', 't3', 't4', 't5'], y: [5, 1, 7, 5, 9] }; const data2 = { x: ['t1', 't2', 't3', 't4', 't5'], y: [2, 8, 4, 6, 3] }; line.setData([data, data2]); const bar = grid.set(0, 6, 6, 6, contrib.bar, { label: 'Process Memory (MB)', barWidth: 4, barSpacing: 6, xOffset: 0, maxHeight: 100 }); bar.setData({ titles: ['Proc A', 'Proc B', 'Proc C'], data: [85, 40, 65] }); screen.key(['escape', 'q', 'C-c'], function(ch, key) { return process.exit(0); }); screen.render();

Debug

Known issues

gotchablessed-contrib is primarily a CommonJS module. While TypeScript types are provided, direct ESM `import` statements may require specific `tsconfig` settings (`esModuleInterop: true`) or Node.js loader configurations to function correctly at runtime. The common pattern remains `require()`.

fix

For CJS environments: `const contrib = require('blessed-contrib');`. For TypeScript/ESM projects, use `import * as contrib from 'blessed-contrib';` and ensure `esModuleInterop` is enabled in your `tsconfig.json`.

affects: >=1.0.0

gotchaWidgets must be appended to a `blessed` screen or a `blessed-contrib` grid instance BEFORE attempting to set their data. Failing to do so can lead to unexpected rendering issues or errors.

fix

Always call `screen.append(widget)` or `grid.set(...)` before any `widget.setData()` calls. E.g., `screen.append(line); line.setData([...]);`

affects: >=1.0.0

gotchaFor Windows environments, specific prerequisites (like 'Git for Windows' for a proper terminal emulator) are required to run `blessed-contrib` applications correctly. Without these, rendering may be broken or the application may fail to launch.

fix

Refer to the blessed-contrib documentation or linked resources for Windows setup instructions, typically involving installation of a robust terminal emulator or Git Bash.

affects: >=1.0.0

breakingNo significant breaking changes or security vulnerabilities specific to blessed-contrib have been widely reported or highlighted in recent versions (4.x) based on available documentation. Major API changes are infrequent.

fix

Maintain regular updates to the latest minor/patch versions. Always test against new major versions of `blessed` as `blessed-contrib` is tightly coupled.

affects: >=4.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use `require()` in an ES Module context without proper configuration.

fix

If running in an ESM environment, use `import * as contrib from 'blessed-contrib';` or ensure your build system/Node.js setup correctly transpiles or handles CommonJS interop. Alternatively, ensure your file is treated as CommonJS (e.g., `.cjs` extension or `"type": "commonjs"` in package.json).

TypeError: Cannot read properties of undefined (reading 'line')

The `contrib` object was not correctly imported or is `undefined` when attempting to access a widget constructor like `contrib.line`.

fix

Verify that `const contrib = require('blessed-contrib');` executed successfully and that the `blessed-contrib` package is installed. Ensure no typos in the `contrib` variable name.

Error: blessed-contrib widgets must be appended to a blessed screen first.

A widget's `setData()` method was called before the widget was added to a `blessed` screen or a `blessed-contrib` grid.

fix

Ensure `screen.append(widget)` or `grid.set(...)` is called for the widget instance before any subsequent calls to `widget.setData()` or other methods that require it to be rendered.

Application starts but shows a blank screen or immediately exits.

The `screen.render()` method was not called, or no `screen.key()` handler was implemented to prevent immediate process exit.

fix

Always call `screen.render()` at the end of your setup to draw the UI. Implement `screen.key(['escape', 'q', 'C-c'], () => process.exit(0));` or similar to keep the application running until a specific exit command.

Upgrade

Version history

4.11.0latest on npm

Audit

Dependencies

blessedrequiredCore terminal UI toolkit that blessed-contrib extends. While listed as a direct dependency in package.json, the documentation explicitly instructs users to install it separately.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/yaronn/blessed-contrib ↗

packagehttps://www.npmjs.com/package/blessed-contrib ↗