Skip to main content

Node.js Platform

Using unblessed in Node.js applications.

Installation​

npm install @unblessed/node
# or
pnpm add @unblessed/node
# or
yarn add @unblessed/node

Quick Start​

import { Screen, Box } from "@unblessed/node";

// Create screen
const screen = new Screen({
  smartCSR: true,
  title: "My TUI App",
});

// Create widget
const box = new Box({
  parent: screen,
  top: "center",
  left: "center",
  width: "50%",
  height: "50%",
  content: "Hello from Node.js!",
  border: { type: "line" },
  style: { border: { fg: "cyan" } },
});

// Global key handler
screen.key(["q", "C-c"], () => process.exit(0));

// Render
screen.render();

Runtime Auto-Initialization​

@unblessed/node automatically initializes the Node.js runtime when imported:

// Happens automatically on import
import { Screen } from "@unblessed/node";

// Runtime is ready - no manual setup needed!
const screen = new Screen();

How it works: The package runs auto-init.ts which calls setRuntime(new NodeRuntime()) before any widgets are created.

Node.js-Specific Features​

Direct TTY Access​

Full access to Node.js TTY capabilities:

import { Screen } from "@unblessed/node";

const screen = new Screen({
  input: process.stdin, // Custom input stream
  output: process.stdout, // Custom output stream
  terminal: "xterm-256color", // Terminal type
});

// Access underlying TTY
const tty = screen.program.term;
console.log("Terminal:", tty);

Process Integration​

Integrates with Node.js process:

// Exit handlers
process.on("exit", () => {
  screen.destroy();
  console.log("Cleanup complete");
});

// Signal handlers
process.on("SIGINT", () => {
  screen.destroy();
  process.exit(0);
});

process.on("SIGTERM", () => {
  screen.destroy();
  process.exit(0);
});

// Uncaught errors
process.on("uncaughtException", (error) => {
  screen.destroy();
  console.error("Error:", error);
  process.exit(1);
});

File System Access​

Read files for content or configuration:

import { Box } from "@unblessed/node";
import { readFileSync } from "fs";

const content = readFileSync("./data.txt", "utf8");

const box = new Box({
  parent: screen,
  content: content,
  scrollable: true,
});

Environment Variables​

Access environment configuration:

const isDev = process.env.NODE_ENV === "development";
const debugMode = process.env.DEBUG === "true";

const screen = new Screen({
  debug: debugMode,
  log: isDev ? "./debug.log" : undefined,
});

Screen Options​

Full Option List​

interface ScreenOptions {
  // Program options
  input?: NodeJS.ReadStream; // Input stream (default: process.stdin)
  output?: NodeJS.WriteStream; // Output stream (default: process.stdout)
  terminal?: string; // Terminal type (default: auto-detect)

  // Display options
  smartCSR?: boolean; // Smart cursor save/restore (default: false)
  fastCSR?: boolean; // Fast CSR (default: false)
  resizeTimeout?: number; // Resize debounce (default: 300ms)
  useBCE?: boolean; // Use background color erase (default: false)
  fullUnicode?: boolean; // Full Unicode support (default: false)
  dockBorders?: boolean; // Dock borders (default: false)

  // Behavior options
  cursor?: {
    artificial?: boolean; // Artificial cursor (default: false)
    shape?: "block" | "underline" | "line";
    blink?: boolean;
    color?: string;
  };
  title?: string; // Window title
  forceUnicode?: boolean; // Force Unicode (default: false)
  dump?: boolean; // Dump output to file (default: false)
  log?: string; // Log file path
  debug?: boolean; // Debug mode (default: false)
  warnings?: boolean; // Show warnings (default: false)
  autoPadding?: boolean; // Auto padding (default: false)
  tabc?: string; // Tab char (default: spaces)
}

Common Configurations​

High Performance:

const screen = new Screen({
  smartCSR: true,
  fastCSR: true,
  useBCE: true,
  resizeTimeout: 100,
});

Unicode Support:

const screen = new Screen({
  fullUnicode: true,
  forceUnicode: true,
});

Development/Debug:

const screen = new Screen({
  debug: true,
  log: "./debug.log",
  warnings: true,
  dump: true,
});

Terminal Compatibility​

Supported Terminals​

macOS:

  • iTerm2 ✅
  • Alacritty ✅
  • Kitty ✅
  • Terminal.app ✅

Linux:

  • gnome-terminal ✅
  • konsole ✅
  • xterm ✅
  • terminator ✅

Windows:

  • Windows Terminal ✅
  • ConEmu (partial)
  • cmd.exe (limited)

Terminal Detection​

Automatic terminal detection:

import { Screen } from "@unblessed/node";

const screen = new Screen({
  smartCSR: true, // Auto-detected based on terminal
});

// Check detected terminal
console.log("Terminal:", screen.program.terminal);
console.log("Supports 256 colors:", screen.program.has256);
console.log("Supports true color:", screen.program.hasTrueColor);

Manual Terminal Override​

Override detected terminal:

const screen = new Screen({
  terminal: "xterm-256color", // Force specific terminal type
});

Input Handling​

Keyboard Input​

Handle keyboard events:

// Global keys
screen.key(["C-c", "q"], () => {
  process.exit(0);
});

// Widget-specific keys
textbox.key(["enter"], () => {
  form.submit();
});

// Raw key data
screen.on("keypress", (ch, key) => {
  console.log("Pressed:", key.full);
});

Mouse Input​

Enable mouse support:

const screen = new Screen({
  mouse: true,
  sendFocus: true,
});

box.on("click", (data) => {
  console.log("Clicked at:", data.x, data.y);
});

box.on("wheeldown", () => {
  box.scroll(1);
  screen.render();
});

Raw Mode​

Control raw terminal mode:

// Enable raw mode (default)
screen.program.setRaw(true);

// Disable raw mode
screen.program.setRaw(false);

// Restore mode on exit
process.on("exit", () => {
  screen.program.setRaw(false);
});

Output Control​

Writing to Terminal​

Direct terminal output:

// Write via screen
screen.write("Hello\n");

// Write escape sequences
screen.program.write("\x1b[32mGreen text\x1b[0m\n");

// Position cursor
screen.program.move(10, 5); // Column 10, Row 5
screen.program.write("At position");

Screen Clearing​

Clear screen methods:

// Clear entire screen
screen.clearRegion(0, screen.width, 0, screen.height);

// Clear specific region
screen.clearRegion(x, x + width, y, y + height);

// Full clear and reset
screen.program.clear();
screen.program.home();

Performance Optimization​

Batch Updates​

Minimize renders:

// ❌ Inefficient
for (let i = 0; i < 100; i++) {
  boxes[i].setContent(`Item ${i}`);
  screen.render();
}

// ✅ Efficient
for (let i = 0; i < 100; i++) {
  boxes[i].setContent(`Item ${i}`);
}
screen.render(); // Single render

Throttle Rendering​

For rapid updates:

let lastRender = 0;
const THROTTLE = 16; // ~60 FPS

function update() {
  const now = Date.now();
  if (now - lastRender > THROTTLE) {
    screen.render();
    lastRender = now;
  }
}

Use Smart CSR​

Enable for better performance:

const screen = new Screen({
  smartCSR: true, // Uses scroll regions
  fastCSR: true, // Even faster (may have artifacts)
});

Debugging​

Debug Mode​

Enable debugging:

const screen = new Screen({
  debug: true,
  log: "./debug.log",
});

// Log messages
screen.debug("Something happened");

Logging​

Write to log file:

const screen = new Screen({
  log: "./app.log",
});

// Logs to file
screen.log("Application started");
screen.log("User action:", action);

Dump Output​

Save screen buffer:

const screen = new Screen({
  dump: true, // Saves to ./blessed-${timestamp}.log
});

// Or manually
screen.dumpOutput("./screen-dump.txt");

Best Practices​

1. Clean Exit​

Always clean up:

function cleanup() {
  screen.destroy();
}

process.on("exit", cleanup);
process.on("SIGINT", () => {
  cleanup();
  process.exit(0);
});
process.on("SIGTERM", () => {
  cleanup();
  process.exit(0);
});

2. Error Handling​

Catch and display errors:

process.on("uncaughtException", (error) => {
  // Clean up screen first
  screen.destroy();

  // Then display error
  console.error("Uncaught error:", error);
  process.exit(1);
});

process.on("unhandledRejection", (reason) => {
  screen.destroy();
  console.error("Unhandled rejection:", reason);
  process.exit(1);
});

3. Resize Handling​

Handle terminal resize:

screen.on("resize", () => {
  // Re-layout widgets
  sidebar.width = "30%";
  content.width = "70%";

  // Re-render
  screen.render();
});

4. Use TypeScript​

Get full type safety:

import { Screen, Box, type BoxOptions } from "@unblessed/node";

const options: BoxOptions = {
  parent: screen,
  top: "center",
  left: "center",
  width: "50%",
  height: 10,
};

const box = new Box(options);

Next Steps​