Getting Started

Install #

npm install @b9g/termdom

TermDOM runs on Node, Bun, and Deno, with no native or WASM dependencies.

Usage #

import {TermDOM} from "@b9g/termdom";

const term = new TermDOM();
term.attach();
const {document} = term;

const box = document.createElement("div");
box.style.backgroundColor = "blue";
box.style.color = "white";
box.style.padding = "0 1ch";
box.textContent = "Hello, terminal";

document.body.appendChild(box);

attach() puts the terminal in raw mode and starts rendering. There is no render call: changes to the document appear on the next frame.

The document is drawn below the shell prompt and stays live until the program ends, then stays in the scrollback. The rendering guide covers this, fullscreen, and static output.

For static output, skip attach(). term.renderANSI(html) returns an ANSI string, and term.print(html) writes it to stdout.

Units #

By default, 1px and 1ch are both one cell, so width: 12ch is twelve columns and height: 3px is three rows. Lengths round to whole cells. The cellSize option changes how many CSS pixels a cell is.

Stylesheets #

const style = document.createElement("style");
style.textContent = `
	.card {
		border: 1px solid;
		padding: 0 1ch;
		color: cyan;
	}

	.card:focus {
		border-color: yellow;
	}
`;
document.head.appendChild(style);

Selectors, specificity, inheritance, @media, and custom properties all work.

Quitting #

window.close() ends the session. It leaves the last frame in the scrollback, restores the terminal, and exits the process. Ctrl-C does the same by default.

document.addEventListener("keydown", (ev) => {
	if (ev.key === "q") term.window.close();
});

Frameworks #

Frameworks render into term.document. Most also read globals such as document, window, and Element. installGlobals(term) copies the TermDOM window's properties onto globalThis and returns a function that restores the originals. A few runtime globals are left alone; the API guide lists them.

Frameworks read these globals when their modules load, and static imports load before your code runs. Install the globals first, then import the framework with import():

import {installGlobals, TermDOM} from "@b9g/termdom";

const term = new TermDOM();
installGlobals(term);
const {createRoot} = await import("react-dom/client");
createRoot(term.document.body).render(<App />);

Imported too early, React misses edits that don't come from a key press, such as a paste, and CodeMirror on a Mac binds Cmd, which a terminal can't send.

Vue:

installGlobals(term);
const {createApp} = await import("vue");
createApp(App).mount(term.document.body);

Svelte components must be compiled first, with svelte/compiler and generate: "client" or a bundler plugin. Run with the browser export condition:

node --conditions=browser app.js
import {mount} from "svelte";
import App from "./App.js"; // compiled from App.svelte

installGlobals(term);
mount(App, {target: term.document.body});

Crank doesn't need the globals:

import {renderer} from "@b9g/crank/dom";

renderer.render(<App />, term.document.body);

The hello examples run each framework. examples/todomvc.ts is a full program.

Next #

Edit this page on GitHub