Platform Differences

Key differences between Node.js and Browser platforms.

Quick Comparison

Feature	Node.js	Browser
Runtime	Native Node.js APIs	Polyfills + XTerm.js
Terminal	Direct TTY	XTerm.js emulation
File System	Full access	Bundled terminfo only
Process	Full process control	Limited polyfill
Exit	process.exit()	Destroy screen + terminal
Streams	Native streams	stream-browserify
Buffer	Native Buffer	buffer package
Performance	Faster (native)	Slower (emulation)
Bundle Size	N/A	~150KB gzipped
Mouse	Terminal-dependent	Always available
Resize	SIGWINCH signal	Window resize events

Installation

Node.js

pnpm add @unblessed/node

Includes:

• Node.js runtime implementation
• All core widgets
• Direct TTY support

Browser

pnpm add @unblessed/browser xterm

Includes:

• Browser runtime with polyfills
• All core widgets
• XTerm.js integration

Initialization

Node.js

Automatic runtime initialization:

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

// Runtime auto-initialized with Node.js APIs
const screen = new Screen();

Browser

Requires XTerm.js terminal:

import { Terminal } from 'xterm';
import { Screen, Box } from '@unblessed/browser';

// Create and mount terminal
const term = new Terminal();
term.open(document.getElementById('terminal'));

// Runtime auto-initialized with polyfills
const screen = new Screen({ terminal: term });

API Differences

Screen Creation

Node.js:

const screen = new Screen({
  input: process.stdin,   // Node.js stream
  output: process.stdout, // Node.js stream
  terminal: 'xterm-256color'
});

Browser:

const screen = new Screen({
  terminal: term  // XTerm.js Terminal instance
});

Exiting

Node.js:

screen.key(['q', 'C-c'], () => {
  process.exit(0);  // Works in Node.js
});

Browser:

screen.key(['q', 'C-c'], () => {
  screen.destroy();
  term.dispose();   // Can't actually exit browser
});

File Access

Node.js:

import { readFileSync } from 'fs';

const data = readFileSync('./config.json', 'utf8');
box.setContent(data);

Browser:

// Use fetch API instead
const response = await fetch('/api/config.json');
const data = await response.text();
box.setContent(data);

Environment Variables

Node.js:

const apiKey = process.env.API_KEY;
const isDev = process.env.NODE_ENV === 'development';

Browser:

// process.env is empty object
// Use build-time env variables instead
const apiKey = import.meta.env.VITE_API_KEY;
const isDev = import.meta.env.DEV;

Feature Availability

Available in Both

✅ All widgets (Box, List, Table, Form, etc.) ✅ Event system ✅ Keyboard input ✅ Mouse support ✅ Rendering pipeline ✅ Styling and colors ✅ Content tags ✅ Focus management

Node.js Only

✅ Direct TTY control ✅ File system access ✅ Child processes ✅ Process signals (SIGINT, SIGTERM) ✅ Native streams ✅ process.exit()

Browser Only

✅ XTerm.js integration ✅ DOM integration ✅ Full-screen mode ✅ Browser DevTools ✅ requestAnimationFrame ✅ ResizeObserver ✅ WebWorkers (for async tasks)

Performance Differences

Node.js

Advantages:

• Direct TTY access (no emulation)
• Faster rendering (~6.5ms empty screen)
• Lower memory usage
• Native Buffer operations

Use cases:

• CLI tools
• Server monitoring
• Build tools
• System utilities

Browser

Advantages:

• Works in web browsers
• No installation required
• Cross-platform web apps
• Better for demos/documentation

Trade-offs:

• Slower rendering (~10-15ms empty screen)
• Higher memory usage
• Larger bundle size (~150KB)
• XTerm.js emulation overhead

Use cases:

• Web-based terminals
• Interactive documentation
• Browser DevTools
• Remote terminals

Code Compatibility

Write Once, Run Anywhere

Most code works identically:

// Works in both Node.js and Browser!
import { Screen, Box, List } from '@unblessed/node'; // or browser

const screen = new Screen(/* platform-specific options */);

const box = new Box({
  parent: screen,
  top: 'center',
  left: 'center',
  width: '50%',
  height: '50%',
  content: 'Hello World!',
  border: { type: 'line' }
});

screen.key('q', () => {
  /* platform-specific cleanup */
});

screen.render();

Platform Detection

Detect current platform:

import { getRuntime } from '@unblessed/core/runtime-context';

const runtime = getRuntime();

if (runtime.process.platform === 'browser') {
  // Browser-specific code
  console.log('Running in browser');
} else {
  // Node.js-specific code
  console.log('Running in Node.js');
}

Conditional Imports

Use dynamic imports for platform-specific code:

async function initApp() {
  if (typeof window !== 'undefined') {
    // Browser
    const { Terminal } = await import('xterm');
    const { Screen } = await import('@unblessed/browser');

    const term = new Terminal();
    term.open(document.getElementById('terminal'));

    return new Screen({ terminal: term });
  } else {
    // Node.js
    const { Screen } = await import('@unblessed/node');
    return new Screen();
  }
}

Migration Guide

Node.js to Browser

1. Add XTerm.js:

pnpm add xterm @xterm/addon-fit

2. Change imports:

// Before
import { Screen } from '@unblessed/node';

// After
import { Terminal } from 'xterm';
import { Screen } from '@unblessed/browser';

3. Create terminal:

// Add this
const term = new Terminal();
term.open(document.getElementById('terminal'));

// Update screen creation
const screen = new Screen({ terminal: term });

4. Update file access:

// Before
import { readFileSync } from 'fs';
const data = readFileSync('./data.txt', 'utf8');

// After
const response = await fetch('/data.txt');
const data = await response.text();

5. Update exit handling:

// Before
screen.key('q', () => process.exit(0));

// After
screen.key('q', () => {
  screen.destroy();
  term.dispose();
});

Browser to Node.js

1. Remove XTerm.js:

pnpm remove xterm

2. Change imports:

// Before
import { Terminal } from 'xterm';
import { Screen } from '@unblessed/browser';

// After
import { Screen } from '@unblessed/node';

3. Simplify screen creation:

// Before
const term = new Terminal();
term.open(element);
const screen = new Screen({ terminal: term });

// After
const screen = new Screen();

4. Use Node.js APIs:

// Before
const response = await fetch('/data.txt');
const data = await response.text();

// After
import { readFileSync } from 'fs';
const data = readFileSync('./data.txt', 'utf8');

Best Practices

1. Abstract Platform Differences

Create platform adapters:

// platform.ts
export interface PlatformAdapter {
  createScreen(): Screen;
  readFile(path: string): Promise<string>;
  exit(): void;
}

// node-platform.ts
export class NodePlatform implements PlatformAdapter {
  createScreen() {
    return new Screen();
  }

  async readFile(path: string) {
    return readFileSync(path, 'utf8');
  }

  exit() {
    process.exit(0);
  }
}

// browser-platform.ts
export class BrowserPlatform implements PlatformAdapter {
  constructor(private term: Terminal) {}

  createScreen() {
    return new Screen({ terminal: this.term });
  }

  async readFile(path: string) {
    const response = await fetch(path);
    return response.text();
  }

  exit() {
    // Can't exit browser
    console.log('Application closed');
  }
}

2. Feature Detection

Check for capabilities:

function hasFileSystem(): boolean {
  try {
    const runtime = getRuntime();
    runtime.fs.existsSync('/');
    return true;
  } catch {
    return false;
  }
}

function canExit(): boolean {
  const runtime = getRuntime();
  return runtime.process.platform !== 'browser';
}

3. Progressive Enhancement

Provide fallbacks:

async function loadData(path: string) {
  const runtime = getRuntime();

  if (runtime.process.platform === 'browser') {
    // Browser: fetch from server
    const response = await fetch(path);
    return response.json();
  } else {
    // Node.js: read from file system
    const data = readFileSync(path, 'utf8');
    return JSON.parse(data);
  }
}

4. Shared Widgets

Write platform-agnostic widgets:

export class StatusBar extends Box {
  constructor(options: BoxOptions) {
    super({
      ...options,
      height: 3,
      bottom: 0,
      left: 0,
      right: 0,
      style: { bg: 'blue', fg: 'white' }
    });
  }

  setStatus(message: string) {
    this.setContent(`  ${message}`);
    this.screen?.render();
  }
}

// Works in both platforms!
const status = new StatusBar({ parent: screen });
status.setStatus('Ready');

Common Pitfalls

❌ Using process.exit() in Browser

// DON'T
screen.key('q', () => process.exit(0)); // Throws error in browser

// DO
screen.key('q', () => {
  screen.destroy();
  if (typeof window === 'undefined') {
    process.exit(0);
  }
});

❌ Assuming File System Exists

// DON'T
const config = readFileSync('./config.json'); // Fails in browser

// DO
async function loadConfig() {
  if (hasFileSystem()) {
    return readFileSync('./config.json', 'utf8');
  } else {
    const response = await fetch('/config.json');
    return response.text();
  }
}

❌ Forgetting XTerm.js in Browser

// DON'T
const screen = new Screen(); // Missing terminal in browser

// DO
const term = new Terminal();
term.open(element);
const screen = new Screen({ terminal: term });

Next Steps

• Node.js Platform - Node.js-specific features
• Browser Platform - Browser-specific features
• Examples - Platform-specific examples