Skip to main content

Browser Platform

Running unblessed in web browsers with XTerm.js.

Installation​

npm install @unblessed/browser xterm
# or
pnpm add @unblessed/browser xterm
# or
yarn add @unblessed/browser xterm

Quick Start​

HTML Setup​

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="node_modules/xterm/css/xterm.css" />
  </head>
  <body>
    <div id="terminal"></div>
    <script type="module" src="./app.js"></script>
  </body>
</html>

JavaScript/TypeScript​

import { Terminal } from "xterm";
import { FitAddon } from "@xterm/addon-fit";
import { Screen, Box } from "@unblessed/browser";

// Create XTerm terminal
const term = new Terminal({
  cursorBlink: false,
  fontSize: 14,
  theme: {
    background: "#1e1e1e",
    foreground: "#d4d4d4",
  },
});

// Add fit addon
const fitAddon = new FitAddon();
term.loadAddon(fitAddon);

// Open terminal in DOM
term.open(document.getElementById("terminal"));
fitAddon.fit();

// Create unblessed screen with terminal
const screen = new Screen({ terminal: term });

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

// Render
screen.render();

Runtime Auto-Initialization​

@unblessed/browser automatically initializes the browser runtime:

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

// Runtime is automatically initialized with polyfills
// - File system polyfills with bundled terminfo
// - Process polyfills for events
// - Buffer polyfills
// - Stream polyfills

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

XTerm.js Integration​

Screen Creation​

The Screen automatically detects and wraps XTerm.js:

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

const term = new Terminal();
term.open(element);

// Screen auto-creates XTermAdapter
const screen = new Screen({
  terminal: term,
  smartCSR: true, // Enabled by default
  fastCSR: true, // Enabled by default
  fullUnicode: true, // Enabled by default
});

Terminal Options​

Configure XTerm.js terminal:

const term = new Terminal({
  // Display
  cursorBlink: true,
  cursorStyle: "block",
  fontSize: 14,
  fontFamily: "Monaco, monospace",

  // Size
  rows: 24,
  cols: 80,

  // Theme
  theme: {
    background: "#000000",
    foreground: "#ffffff",
    cursor: "#ffffff",
    black: "#000000",
    red: "#cd0000",
    green: "#00cd00",
    yellow: "#cdcd00",
    blue: "#0000ee",
    magenta: "#cd00cd",
    cyan: "#00cdcd",
    white: "#e5e5e5",
  },

  // Scrolling
  scrollback: 1000,

  // Selection
  allowTransparency: true,
  allowProposedApi: true,
});

Addons​

Use XTerm.js addons:

import { FitAddon } from "@xterm/addon-fit";
import { WebLinksAddon } from "@xterm/addon-web-links";
import { SearchAddon } from "@xterm/addon-search";

const fitAddon = new FitAddon();
const webLinksAddon = new WebLinksAddon();
const searchAddon = new SearchAddon();

term.loadAddon(fitAddon);
term.loadAddon(webLinksAddon);
term.loadAddon(searchAddon);

// Fit terminal to container
fitAddon.fit();

Browser-Specific Features​

Responsive Sizing​

Handle window resize:

const fitAddon = new FitAddon();
term.loadAddon(fitAddon);

window.addEventListener("resize", () => {
  fitAddon.fit();
  screen.render();
});

Full Screen Mode​

Toggle full screen:

const container = document.getElementById("terminal");

function toggleFullScreen() {
  if (!document.fullscreenElement) {
    container.requestFullscreen();
  } else {
    document.exitFullscreen();
  }
}

screen.key("f", toggleFullScreen);

Copy/Paste​

Enable clipboard integration:

// Browser handles copy automatically
// Paste with Ctrl+V or Cmd+V
term.onData((data) => {
  // Handle pasted data
  screen.program.write(data);
});

Mouse Support​

Mouse events work automatically:

const box = new Box({
  parent: screen,
  mouse: true, // Enable mouse
});

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

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

Polyfills​

File System​

Limited file system with bundled terminfo:

// Only bundled files are accessible
// Primarily used internally for terminfo

// Available files:
// - /usr/share/terminfo/x/xterm
// - /usr/share/terminfo/x/xterm-256color
// etc.

Process​

Process polyfill for events:

// process.env - empty object in browser
console.log(process.env); // {}

// process.platform - always 'browser'
console.log(process.platform); // 'browser'

// process.exit() - throws error in browser
// Don't use process.exit() in browser code!

Buffer​

Full Buffer API via buffer package:

import { Buffer } from "buffer";

const buf = Buffer.from("Hello");
console.log(buf.toString()); // 'Hello'

Streams​

Stream polyfills via stream-browserify:

import { Readable, Writable } from "stream";

// Works like Node.js streams
const readable = new Readable();
readable.push("data");

Building for Production​

Vite​

Recommended bundler for browser apps:

// vite.config.ts
import { defineConfig } from "vite";

export default defineConfig({
  resolve: {
    alias: {
      buffer: "buffer/",
      stream: "stream-browserify",
      util: "util/",
    },
  },
  define: {
    "process.env": {},
    global: "globalThis",
  },
  optimizeDeps: {
    include: ["buffer", "stream-browserify", "util"],
  },
});

Webpack​

Configure webpack:

// webpack.config.js
module.exports = {
  resolve: {
    fallback: {
      buffer: require.resolve("buffer/"),
      stream: require.resolve("stream-browserify"),
      util: require.resolve("util/"),
    },
  },
  plugins: [
    new webpack.ProvidePlugin({
      Buffer: ["buffer", "Buffer"],
      process: "process/browser",
    }),
  ],
};

Bundle Size​

Optimize bundle size:

// Only import what you need
import { Screen, Box, List } from "@unblessed/browser";

// Tree-shaking removes unused widgets
// Final bundle: ~150KB gzipped (including XTerm.js)

Examples​

Interactive Dashboard​

import { Terminal } from "xterm";
import { FitAddon } from "@xterm/addon-fit";
import { Screen, Box, List } from "@unblessed/browser";

const term = new Terminal();
const fitAddon = new FitAddon();
term.loadAddon(fitAddon);
term.open(document.getElementById("terminal"));
fitAddon.fit();

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

const header = new Box({
  parent: screen,
  top: 0,
  left: 0,
  width: "100%",
  height: 3,
  content: "{center}{bold}Dashboard{/bold}{/center}",
  tags: true,
  style: { bg: "blue", fg: "white" },
});

const sidebar = new List({
  parent: screen,
  top: 3,
  left: 0,
  width: "30%",
  height: "100%-3",
  items: ["Overview", "Analytics", "Settings"],
  keys: true,
  mouse: true,
  style: {
    selected: { bg: "cyan", fg: "black" },
  },
});

const content = new Box({
  parent: screen,
  top: 3,
  left: "30%",
  width: "70%",
  height: "100%-3",
  border: { type: "line" },
});

sidebar.on("select", (item) => {
  content.setContent(`Selected: ${item.getText()}`);
  screen.render();
});

sidebar.focus();
screen.render();

Live Code Editor​

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

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

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

const editor = new Textbox({
  parent: screen,
  top: 0,
  left: 0,
  width: "100%",
  height: "50%",
  border: { type: "line" },
  label: " Editor ",
  inputOnFocus: true,
  keys: true,
  mouse: true,
});

const output = new Box({
  parent: screen,
  top: "50%",
  left: 0,
  width: "100%",
  height: "50%",
  border: { type: "line" },
  label: " Output ",
  scrollable: true,
  mouse: true,
});

editor.on("submit", (value) => {
  try {
    const result = eval(value);
    output.setContent(`> ${result}`);
  } catch (error) {
    output.setContent(`Error: ${error.message}`);
  }
  screen.render();
});

editor.focus();
screen.render();

Performance Tips​

1. Throttle Renders​

Limit render frequency:

let rafId: number | null = null;

function scheduleRender() {
  if (rafId === null) {
    rafId = requestAnimationFrame(() => {
      screen.render();
      rafId = null;
    });
  }
}

// Use instead of direct screen.render()
box.setContent("Update");
scheduleRender();

2. Virtualize Long Lists​

Only render visible items:

class VirtualList extends List {
  renderVisibleItems() {
    const start = this.childBase;
    const end = start + this.height;

    // Only render items in view
    return this.items.slice(start, end);
  }
}

3. Debounce Resize​

Prevent excessive re-renders:

let resizeTimeout: number;

window.addEventListener("resize", () => {
  clearTimeout(resizeTimeout);
  resizeTimeout = setTimeout(() => {
    fitAddon.fit();
    screen.render();
  }, 100);
});

Debugging​

Console Logging​

Debug to browser console:

screen.on("keypress", (ch, key) => {
  console.log("Key:", key);
});

box.on("click", (data) => {
  console.log("Click:", data);
});

DevTools​

Use browser DevTools:

// Expose screen globally for debugging
(window as any).screen = screen;

// In console:
// > screen.children
// > screen.render()

Performance Profiling​

Use Chrome DevTools Performance tab:

console.time("render");
screen.render();
console.timeEnd("render");

Limitations​

No Process.exit()​

Can't exit browser:

// ❌ Don't use
screen.key("q", () => process.exit(0));

// ✅ Use instead
screen.key("q", () => {
  screen.destroy();
  term.dispose();
});

No File System​

Limited to bundled files:

// ❌ Won't work
fs.readFileSync("./myfile.txt");

// ✅ Fetch from server instead
fetch("/api/myfile.txt")
  .then((res) => res.text())
  .then((data) => box.setContent(data));

No Child Processes​

Can't spawn processes:

// ❌ Not available
child_process.spawn("ls");

// ✅ Use web APIs instead
// - WebWorkers for background tasks
// - WebSockets for server communication

Best Practices​

1. Handle Terminal Lifecycle​

Clean up properly:

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

window.addEventListener("beforeunload", cleanup);

2. Responsive Design​

Adapt to container size:

const fitAddon = new FitAddon();
term.loadAddon(fitAddon);

const resizeObserver = new ResizeObserver(() => {
  fitAddon.fit();
  screen.render();
});

resizeObserver.observe(container);

3. Error Boundaries​

Catch and display errors:

window.addEventListener("error", (event) => {
  errorBox.setContent(`Error: ${event.message}`);
  screen.render();
});

4. Progressive Enhancement​

Detect browser capabilities:

const hasClipboard = !!navigator.clipboard;
const hasFullscreen = !!document.fullscreenEnabled;

if (hasFullscreen) {
  screen.key("f", toggleFullScreen);
}

Next Steps​