README.md

@acode/terminal

Reusable terminal UI for browser projects. It returns an HTMLElement, keeps the renderer pluggable, and separates UI rendering from transport concerns.

Install

bun add @acode/terminal

Usage

import { createTerminal, WebSocketTerminalTransport } from "@acode/terminal";
import "@acode/terminal/style.css";

const terminal = createTerminal();

document.body.append(terminal);
terminal.controller.mount();

terminal.controller.setTransport(
	new WebSocketTerminalTransport({
		url: "ws://localhost:3000/terminals/demo",
	}),
);

await terminal.controller.connect();
terminal.controller.focus();

xterm customization

import { createTerminal, XtermEngine } from "@acode/terminal";

const terminal = createTerminal({
	engine: new XtermEngine({
		fontSize: 13,
		fontFamily: "JetBrains Mono",
		renderer: "auto",
		imageSupport: true,
		fontLigatures: true,
	}),
});

Design

• createTerminal() returns an HTMLElement with a controller property.
• TerminalController handles lifecycle, events, and transport wiring.
• XtermEngine is the default renderer implementation.
• WebSocketTerminalTransport is an optional transport layer.
• Custom renderers can implement the exported TerminalEngine interface.

Testing

bun run test

An example package-level test lives in test/example.test.ts and demonstrates how to plug in a custom engine and transport.