Architecture

Architecture

TermUI is a Bun monorepo with 13 packages. Each package has one job.

Packages

Package	Job
@termuijs/core	Layout engine, renderer, terminal I/O, input parser, App lifecycle
@termuijs/widgets	Display widgets: Box, Text, Table, charts, badges, progress
@termuijs/ui	Interactive components: Select, Form, Modal, Tabs, AppShell
@termuijs/jsx	JSX runtime and React-style hooks
@termuijs/store	Global signal-based state
@termuijs/tss	Theming and style tokens
@termuijs/motion	Animations and the timer pool
@termuijs/router	Path-based screen routing
@termuijs/data	Real-time data providers (CPU, memory, disk)
@termuijs/testing	Headless render harness for tests
@termuijs/dev-server	Hot-reload dev server
@termuijs/quick	Convenience re-exports for fast setup
create-termui-app	Project scaffolding CLI

Render flow

1. Your component tree builds a layout node tree.
2. The layout engine resolves positions and sizes with flexbox rules.
3. Widgets write cells to a back buffer.
4. The differential renderer compares front and back buffers.
5. Only changed cells emit ANSI escape sequences to stdout.

This keeps redraws small. A stable frame writes zero bytes.

Capability detection

@termuijs/core reads the terminal environment at startup. It detects Unicode support, color depth, and TTY state. Widgets check caps.unicode before drawing box characters and fall back to ASCII when needed.

How packages depend on each other

• core depends on nothing internal.
• widgets depends on core.
• ui depends on core and widgets.
• jsx depends on core.
• Everything else builds on these.

Keep this direction. A package must not import from one that sits above it.