Overview

Cascade is a native terminal UI runtime and component model, written in Zig with TypeScript APIs. This documentation introduces the architecture, core concepts, components, bindings and reference topics.

Quick start

Get up and running by scaffolding a new project and executing your first interactive application.

Use the Bun package manager to create a Cascade project and start it in development mode.

bun create @cascadetui/create-cascade my-app
cd my-app
bun install
bun run dev

The generated project typically includes a single entry file, a minimal demo UI and scripts for development and production. Start by making a small change (like updating a label) and re-run bun run dev to confirm your workflow.

When troubleshooting, keep these quick checks in mind: verify your terminal supports the required features (mouse, alternate screen), confirm the app exits cleanly, and enable the built‑in console overlay for logs.

# Run with additional runtime diagnostics
CASCADE_LOG_CRASH_REPORTS=1 bun run dev

Documentation map

The rest of the documentation is organised by topic. Core Concepts explain how the renderer works, how to build and compose renderables, and how to manage lifecycle and input. Components provide examples of each built‑in terminal primitive. Bindings show how to use Cascade with frameworks like Solid and React. Reference covers environment variables and Tree‑sitter integration.

If you are new to Cascade, read in this order: Renderer, Renderables, Layout, Keyboard, then the component pages you need for your UI (Text, Box, Input, ScrollBox, Diff). For app‑style architecture, the Solid/React bindings help you structure state and events cleanly.

Cheat sheet

Goal	Use	Minimal snippet
Start a new app	`create-cascade`	`bun create cascade`
Imperative UI	`@cascadetui/core` renderables	`new BoxRenderable(renderer, ...)`
Declarative (no framework)	`constructs` + `instantiate`	`instantiate(renderer, vnode)`
React UI	`@cascadetui/react`	`createRoot(renderer).render(...)`
Solid UI	`@cascadetui/solid`	`render(() => <App />)`

Tip: if you’re unsure which approach to pick, start with React or Solid for app-like UIs (state + composition). Use renderables for low-level control or when you want to mutate objects in-place.