Repository Layout

This page describes the top-level structure of the Rezi monorepo. The repository uses npm workspaces to manage multiple packages from a single root.

Directory Tree

Rezi/
  packages/
    core/           @rezi-ui/core
    node/           @rezi-ui/node
    native/         @rezi-ui/native
    jsx/            @rezi-ui/jsx
    testkit/        @rezi-ui/testkit
    create-rezi/    create-rezi CLI
    bench/          @rezi-ui/bench (benchmark suite)
  examples/
    hello-counter/
    raw-draw-demo/
  docs/
  scripts/
  vendor/
    zireael/
  .github/
    workflows/
  out/              (build output, gitignored)

Root Configuration Files

packages/

Each package is an npm workspace member published independently to the npm registry (except bench, which is private).

core -- @rezi-ui/core

The runtime-agnostic TypeScript framework. Contains the complete widget system, layout engine, reconciler, drawlist builder, event parser, theme system, and keybinding manager. This package must not import any Node.js-specific APIs (Buffer, worker_threads, node:* modules). Portability is enforced by scripts/check-core-portability.mjs.

Key subdirectories:

• src/app/ -- Application runtime (createApp, widget renderer, turn scheduler, state machine)
• src/runtime/ -- VNode commit and reconciliation (commit.ts, reconcile.ts)
• src/layout/ -- Flexbox-style layout engine, text measurement
• src/renderer/ -- Stack-based DFS renderer, drawlist emission
• src/drawlist/ -- ZRDL binary drawlist builder (v1 and v2)
• src/protocol/ -- ZREV event batch parser
• src/widgets/ -- Built-in widget definitions
• src/theme/ -- Theme tokens, built-in themes
• src/keybindings/ -- Keybinding manager
• src/repro/ -- Repro bundle capture and replay

node -- @rezi-ui/node

The Node.js / Bun backend. Provides createNodeBackend() and the convenience createNodeApp() wrapper. Manages terminal raw mode, alternate screen, signal handling, and the poll/submit loop against the native addon.

native -- @rezi-ui/native

The N-API addon wrapping the Zireael C engine via napi-rs. Ships prebuilt binaries for linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64, and win32-arm64. See Native addon for details.

jsx -- @rezi-ui/jsx

JSX runtime for Rezi. Provides jsx, jsxs, and Fragment exports so applications can use JSX syntax to build widget trees. Consumed via tsconfig.json JSX settings.

testkit -- @rezi-ui/testkit

Test utilities for Rezi applications. Provides headless backends, mock event sources, and assertion helpers for testing widget behavior without a real terminal.

create-rezi -- create-rezi

CLI scaffolding tool. Running npm create rezi generates a new Rezi project from built-in templates with proper package.json, tsconfig.json, and example code.

bench -- @rezi-ui/bench (private)

Benchmark suite for comparing Rezi's rendering pipeline against other TUI frameworks. Includes profiling scripts for individual pipeline phases. Not published to npm.

Key files:

• src/profile-phases.ts -- Phase-by-phase profiling (layout, render, build)
• src/profile-construction.ts -- VNode construction benchmarks
• src/run.ts -- Benchmark entry point (compiled to dist/run.js, run with --expose-gc)

examples/

Runnable example applications that demonstrate Rezi usage.

hello-counter

A minimal counter application. Demonstrates createNodeApp, state updates, and basic widget composition.

raw-draw-demo

Demonstrates the low-level draw API (app.draw()) for direct terminal drawing without the widget system.

docs/

The MkDocs Material documentation site source. Markdown files are organized to mirror the site navigation. The site is built by scripts/docs.sh and deployed via the docs.yml GitHub Actions workflow.

See Docs for the documentation workflow.

scripts/

Build, test, and CI automation scripts.

vendor/zireael

The Zireael C rendering engine, pinned as a git submodule. This is the upstream source used by @rezi-ui/native for compilation. The native package keeps its own vendored snapshot at packages/native/vendor/zireael as the compile-time source.

Initialize with:

git submodule update --init --recursive

.github/workflows/

CI/CD workflows powered by GitHub Actions.

Build Output (gitignored)

See Also

• Build
• Style guide
• Testing