blessed-contrib Deployment and Usage Guide

Prerequisites

• Node.js (version 10 or higher)
• npm (Node Package Manager)
• Terminal that supports ANSI art (Linux, macOS, or Windows with appropriate terminal emulator)

Installation

For building custom projects:

npm install blessed blessed-contrib

For running the demo:

git clone https://github.com/yaronn/blessed-contrib.git
cd blessed-contrib
npm install
node ./examples/dashboard.js

Configuration

No specific environment variables or API keys are required for basic usage. The library works with standard terminal configurations.

Build & Run

Running the Demo Application

The demo application is located in examples/dashboard.js. To run it:

cd blessed-contrib
node examples/dashboard.js

Creating Custom Applications

Create a new JavaScript file and require the necessary modules:

var blessed = require('blessed')
  , contrib = require('blessed-contrib')
  , screen = blessed.screen()

Then create widgets and append them to the screen:

var line = contrib.line({
  style: {
    line: "yellow",
    text: "green",
    baseline: "black"
  },
  xLabelPadding: 3,
  xPadding: 5,
  label: 'Title'
})

var data = {
  x: ['t1', 't2', 't3', 't4'],
  y: [5, 1, 7, 5]
}

screen.append(line)
line.setData([data])

screen.key(['escape', 'q', 'C-c'], function(ch, key) {
  return process.exit(0);
});

screen.render()

Deployment

Local Development

For local development, simply run your application with Node.js:

node your-application.js

Production Deployment

Since this is a terminal-based dashboard library, deployment considerations include:

1. SSH Access: The library is friendly to SSH connections, making it suitable for remote server monitoring
2. Terminal Emulators: Ensure the target environment has a compatible terminal emulator
3. Process Management: Use tools like pm2 or systemd to keep your dashboard running:

npm install -g pm2
pm2 start your-application.js --name "dashboard"

Platform Considerations

• Linux Servers: Ideal for system monitoring dashboards
• Windows: Requires additional setup (see Windows prerequisites)
• Cloud VMs: Perfect for remote server monitoring via SSH

Troubleshooting

Common Issues

1. Widgets not displaying correctly

   • Ensure screen.append() is called before setData()
   • Check that your terminal supports ANSI art

2. Colors not appearing

   • Verify your terminal supports color output
   • Try different color values in the widget options

3. Performance issues

   • Reduce the number of widgets
   • Increase the update interval for data

4. Windows compatibility

   • Follow the Windows prerequisites guide
   • Use a modern terminal emulator like Windows Terminal

Widget-Specific Issues

• Line Charts: Ensure data arrays are properly formatted with x and y properties
• Bar Charts: Check that titles and data arrays have matching lengths
• Maps: Verify longitude and latitude values are within valid ranges

Debug Mode

To enable debug output, run your application with the DEBUG environment variable:

DEBUG=blessed-contrib node your-application.js