tui-builder

Building Terminal UIs (TUIs)

Battle-tested rules from shipping Ink + React TUIs. The deep stack documented here is Ink/React on Node; the underlying principles — render into the alternate screen, control resize-handler ordering, treat size as state — transfer to other TUI frameworks even when the exact escape codes differ.

The thing to get right, because it's gotten wrong every time, is terminal resize. Ink renders by diffing its previous output and repositioning the cursor, not by clearing and redrawing. On resize that model breaks three ways at once:

• content Ink no longer "owns" stays visible
• the cursor lands at an unknown position, so Ink's positioning math is off
• a taller terminal re-reveals old lines that were previously offscreen

Every resize bug below is a variation of this one root cause.

Rule 1 — Render into the alternate screen buffer

Prevents: ghost content — old frames stacking up, the logo repeating, a scrollbar appearing on resize.

Why: Ink writes to the normal terminal buffer, which has scrollback. Shrink the window and the terminal shows scrollback; grow it and old output is still in the buffer at the now-visible positions. Ink overwrites from the cursor but can't erase content it no longer knows about. The alternate screen has no scrollback at all, so there's nothing to bleed in from.

Enter with \x1B[?1049h before render(), exit with \x1B[?1049l. Hide the cursor (\x1B[?25l) while you're in it — cleaner, and it avoids cursor flicker on re-renders.

// Before render():
process.stdout.write('\x1B[?1049h\x1B[?25l'); // enter alt screen, hide cursor
const restoreTerminal = () => process.stdout.write('\x1B[?25h\x1B[?1049l');
process.once('exit', restoreTerminal);

Always register the process.once('exit', restoreTerminal) handler so the terminal is restored even on crash. Skip it and you strand the user in alt-screen mode after the program exits.

Rule 2 — Register the clear handler in the entry point, BEFORE render()