mirror of
https://github.com/aphrody-labs/opentui.git
synced 2026-10-13 21:08:53 +00:00
readme: clarify project overview (#1417)
This commit is contained in:
Simon Klee authored and GitHub committed
1 parent
4d983f032b
commit
0b06560ed4
5 files changed
+126
-291
No files matched your search
@@ -1,16 +0,0 @@
|
||||
# Contributing to Opentui
|
||||
|
||||
Bug fixes and feature suggestions are always welcome. For bug fixes, open a PR
|
||||
for reviews. Feature suggestions are subject to discussion via issues.
|
||||
|
||||
## Code style
|
||||
|
||||
Reference existing [AGENTS.md](https://github.com/anomalyco/opentui/blob/main/AGENTS.md) or project conventions if applicable.
|
||||
|
||||
## Code of conduct
|
||||
|
||||
- Treat everyone with respect and empathy. We do not tolerate harassment, discrimination, or personal attacks.
|
||||
- Be kind, constructive, and assume good intent.
|
||||
- Keep feedback specific and actionable; critique code, not people.
|
||||
- No unsolicited DMs for support unless invited.
|
||||
- Follow project guidelines and maintainers’ decisions.
|
||||
@@ -1,97 +1,80 @@
|
||||
# OpenTUI
|
||||
<p align="center">
|
||||
<a href="https://opentui.com">
|
||||
<img alt="OpenTUI logo" src="https://opentui.com/opentui-logo-auto.svg" width="270" />
|
||||
</a>
|
||||
</p>
|
||||
|
||||
<div align="center">
|
||||
<a href="https://www.npmjs.com/package/@opentui/core"><img alt="npm" src="https://img.shields.io/npm/v/@opentui/core?style=flat-square" /></a>
|
||||
<a href="https://github.com/anomalyco/opentui/actions/workflows/build-core.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/anomalyco/opentui/build-core.yml?style=flat-square&branch=main" /></a>
|
||||
<a href="https://github.com/msmps/awesome-opentui"><img alt="awesome opentui list" src="https://awesome.re/badge-flat.svg" /></a>
|
||||
<a href="https://www.npmjs.com/package/@opentui/core"><img alt="npm version" src="https://img.shields.io/npm/v/@opentui/core?style=flat-square" /></a>
|
||||
<a href="https://github.com/anomalyco/opentui/actions/workflows/build-core.yml"><img alt="Core build status" src="https://img.shields.io/github/actions/workflow/status/anomalyco/opentui/build-core.yml?style=flat-square&branch=main" /></a>
|
||||
</div>
|
||||
|
||||
OpenTUI is a native terminal UI core written in Zig with TypeScript bindings. The native core exposes a C ABI and can be used from any language. OpenTUI powers [OpenCode](https://opencode.ai) in production today. It is an extensible core with a focus on correctness, stability, and high performance. It provides a component-based architecture with flexible layout capabilities, allowing you to create complex terminal applications.
|
||||
OpenTUI is a library to build terminal user interfaces.
|
||||
|
||||
Docs: https://opentui.com/docs/getting-started
|
||||
- It is written in Zig.
|
||||
- You write TypeScript directly or through React and Solid.
|
||||
- You arrange boxes and text with flexbox.
|
||||
- You add selects, inputs, and scroll boxes with keyboard and mouse controls.
|
||||
- You can play sounds, show images, and render 3D graphics.
|
||||
|
||||
Quick start with [bun](https://bun.sh) and [create-tui](https://github.com/msmps/create-tui):
|
||||
OpenCode uses OpenTUI in production for millions of users.
|
||||
|
||||
```bash
|
||||
bun create tui
|
||||
```
|
||||
[Website](https://opentui.com) | [Documentation](https://opentui.com/docs) | [Packages](https://opentui.com/packages)
|
||||
|
||||
This monorepo contains the following packages:
|
||||
## Packages
|
||||
|
||||
- [`@opentui/native`](packages/native) - Private workspace package containing the Zig implementation, tests, and benchmarks.
|
||||
- [`@opentui/core`](packages/core) - TypeScript bindings for OpenTUI's native Zig core, with an imperative API and all primitives.
|
||||
- [`@opentui/core`](packages/core) - Native terminal UI library with TypeScript bindings.
|
||||
- [`@opentui/react`](packages/react) - React renderer for building terminal user interfaces with OpenTUI Core.
|
||||
- [`@opentui/solid`](packages/solid) - Solid renderer for building terminal user interfaces with OpenTUI Core.
|
||||
- [`@opentui/keymap`](packages/keymap) - Key binding and command routing library for terminal and browser applications.
|
||||
- [`@opentui/qrcode`](packages/qrcode) - QR code encoder and renderable with React and Solid surfaces.
|
||||
- [`@opentui/three`](packages/three) - Three.js WebGPU renderer for OpenTUI.
|
||||
- [`@opentui/solid`](packages/solid) - The SolidJS reconciler for OpenTUI.
|
||||
- [`@opentui/react`](packages/react) - The React reconciler for OpenTUI.
|
||||
- [`@opentui/keymap`](packages/keymap) - Shared command, keybinding, and sequence engine.
|
||||
- [`@opentui/qrcode`](packages/qrcode) - QR encoder and terminal renderable integrations.
|
||||
- [`@opentui/ssh`](packages/ssh) - Serve imperative, React, and Solid OpenTUI applications over SSH.
|
||||
- [`@opentui/examples`](packages/examples) - Example browser and standalone examples executable build.
|
||||
- [`@opentui/web`](packages/web) - Private documentation website and installable AI agent skill source.
|
||||
- [`@opentui/ssh`](packages/ssh) - SSH server integration for OpenTUI applications.
|
||||
|
||||
## Install
|
||||
**Private packages**
|
||||
|
||||
NOTE: You must have [Zig](https://ziglang.org/learn/getting-started/) installed on your system to build the packages.
|
||||
- [`@opentui/native`](packages/native) - Private workspace with the Zig implementation, native tests, and benchmarks.
|
||||
- [`@opentui/examples`](packages/examples) - Private workspace with example applications and a standalone examples executable.
|
||||
- [`@opentui/web`](packages/web) - Private workspace with the documentation website and the AI agent skill.
|
||||
|
||||
### TypeScript/JavaScript
|
||||
## AI agent skill
|
||||
|
||||
```bash
|
||||
bun install @opentui/core
|
||||
```
|
||||
|
||||
## AI Agent Skill
|
||||
|
||||
Teach your AI coding assistant OpenTUI's APIs and patterns.
|
||||
|
||||
**Universal skill install with [`npx skills`](https://skills.sh):**
|
||||
Install the OpenTUI documentation as a skill for your AI coding assistant with [`npx skills`](https://skills.sh):
|
||||
|
||||
```bash
|
||||
npx skills add anomalyco/opentui --skill opentui
|
||||
```
|
||||
|
||||
Install globally for every project:
|
||||
|
||||
```bash
|
||||
npx skills add anomalyco/opentui --skill opentui -g
|
||||
```
|
||||
|
||||
OpenCode uses the same install command. No separate installer is needed.
|
||||
|
||||
## Try Examples
|
||||
|
||||
You can quickly try out OpenTUI examples without cloning the repository:
|
||||
|
||||
**For macOS, Linux, WSL, Git Bash:**
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/anomalyco/opentui/main/packages/examples/install.sh | sh
|
||||
```
|
||||
|
||||
**For Windows (PowerShell/CMD):**
|
||||
|
||||
Download the latest release directly from [GitHub Releases](https://github.com/anomalyco/opentui/releases/latest)
|
||||
|
||||
## Running Examples (from the repo root)
|
||||
|
||||
### TypeScript Examples
|
||||
|
||||
```bash
|
||||
bun install
|
||||
cd packages/examples
|
||||
bun run dev
|
||||
```
|
||||
Add `-g` to install the skill globally.
|
||||
|
||||
## Development
|
||||
|
||||
See the [Development Guide](packages/core/docs/development.md) for building, testing, debugging, and local development linking.
|
||||
Development requires Bun 1.3.0 or later and Zig 0.16.0.
|
||||
|
||||
### Documentation
|
||||
See [AGENTS.md](AGENTS.md) for engineering, tooling, and verification conventions.
|
||||
|
||||
- [Website docs](https://opentui.com/docs/getting-started) - Guides and API references
|
||||
- [Development Guide](packages/core/docs/development.md) - Building, testing, and local dev linking
|
||||
- [Getting Started](https://opentui.com/docs/getting-started) - API and usage guide
|
||||
- [Environment Variables](https://opentui.com/docs/reference/env-vars) - Configuration options
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
## Showcase
|
||||
Run package scripts from their package directory. Run `bun run build` from the repository root after you change
|
||||
native code or cross-package build outputs. Ordinary TypeScript changes do not require a root build.
|
||||
|
||||
Consider showcasing your work on the [awesome-opentui](https://github.com/msmps/awesome-opentui) list. A curated list of awesome resources and terminal user interfaces built with OpenTUI.
|
||||
Run repository tests and static checks from the repository root:
|
||||
|
||||
```bash
|
||||
bun run test
|
||||
bun run fmt:check
|
||||
bun run lint
|
||||
```
|
||||
|
||||
To link the source packages into a Bun-managed project, install that project's dependencies, then run
|
||||
`./scripts/link-opentui-dev.sh /path/to/project` from the repository root. Add `--react` or `--solid` when needed.
|
||||
|
||||
## Contributing
|
||||
|
||||
OpenTUI is open for contributions.
|
||||
|
||||
## License
|
||||
|
||||
OpenTUI is licensed under the [MIT License](LICENSE).
|
||||
+57
-50
@@ -1,63 +1,70 @@
|
||||
# OpenTUI Core
|
||||
<!-- Keep the project introduction aligned with the repository README and opentui.com. -->
|
||||
|
||||
OpenTUI is a native terminal UI core written in Zig with TypeScript bindings. The native core exposes a C ABI and can be used from any language. OpenTUI powers OpenCode in production today and will also power terminal.shop. It is an extensible core with a focus on correctness, stability, and high performance. It provides a component-based architecture with flexible layout capabilities, allowing you to create complex terminal applications.
|
||||
<p align="center">
|
||||
<a href="https://opentui.com">
|
||||
<img alt="OpenTUI logo" src="https://opentui.com/opentui-logo-auto.svg" width="270" />
|
||||
</a>
|
||||
</p>
|
||||
|
||||
## Documentation
|
||||
<div align="center">
|
||||
<a href="https://www.npmjs.com/package/@opentui/core"><img alt="npm version" src="https://img.shields.io/npm/v/@opentui/core?style=flat-square" /></a>
|
||||
<a href="https://github.com/anomalyco/opentui/actions/workflows/build-core.yml"><img alt="Core build status" src="https://img.shields.io/github/actions/workflow/status/anomalyco/opentui/build-core.yml?style=flat-square&branch=main" /></a>
|
||||
</div>
|
||||
|
||||
- [Getting Started](https://opentui.com/docs/getting-started) - API and usage guide
|
||||
- [Development Guide](docs/development.md) - Building, testing, and contributing
|
||||
- [Tree-Sitter](https://opentui.com/docs/reference/tree-sitter) - Syntax highlighting integration
|
||||
- [Renderables](https://opentui.com/docs/core-concepts/renderables) - Understanding the component model
|
||||
- [Environment Variables](https://opentui.com/docs/reference/env-vars) - Configuration options
|
||||
OpenTUI is a library to build terminal user interfaces.
|
||||
|
||||
## Install
|
||||
- It is written in Zig.
|
||||
- You write TypeScript directly or through React and Solid.
|
||||
- You arrange boxes and text with flexbox.
|
||||
- You add selects, inputs, and scroll boxes with keyboard and mouse controls.
|
||||
- You can play sounds, show images, and render 3D graphics.
|
||||
|
||||
```bash
|
||||
bun install @opentui/core
|
||||
```
|
||||
OpenCode uses OpenTUI in production for millions of users.
|
||||
|
||||
## Build
|
||||
[Website](https://opentui.com) | [Documentation](https://opentui.com/docs) | [Packages](https://opentui.com/packages)
|
||||
|
||||
```bash
|
||||
bun run build
|
||||
```
|
||||
## OpenTUI Core
|
||||
|
||||
This creates platform-specific libraries that are automatically loaded by the TypeScript layer.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
bun install
|
||||
cd ../examples
|
||||
bun run dev
|
||||
```
|
||||
|
||||
## Benchmarks
|
||||
|
||||
Run native performance benchmarks:
|
||||
|
||||
```bash
|
||||
bun run bench:native
|
||||
```
|
||||
|
||||
See [the native benchmark runner](../native/src/bench.zig) for options such as `--filter` and `--mem`.
|
||||
|
||||
NativeSpanFeed TypeScript benchmarks:
|
||||
|
||||
- [src/benchmark/native-span-feed-benchmark.md](src/benchmark/native-span-feed-benchmark.md)
|
||||
|
||||
## CLI Renderer
|
||||
|
||||
### Renderables
|
||||
|
||||
Renderables are hierarchical objects that can be positioned, nested, styled and rendered to the terminal:
|
||||
`@opentui/core` supplies the renderer and TypeScript API. You use imperative renderables and events directly. The
|
||||
TypeScript packages call native Zig through an internal foreign function interface (FFI) boundary.
|
||||
|
||||
```typescript
|
||||
import { createCliRenderer, TextRenderable } from "@opentui/core"
|
||||
import { TextRenderable, createCliRenderer } from "@opentui/core"
|
||||
|
||||
const renderer = await createCliRenderer()
|
||||
const renderer = await createCliRenderer({ exitOnCtrlC: true })
|
||||
|
||||
const obj = new TextRenderable(renderer, { id: "my-obj", content: "Hello, world!" })
|
||||
|
||||
renderer.root.add(obj)
|
||||
renderer.root.add(new TextRenderable(renderer, { content: "Hello, OpenTUI!" }))
|
||||
```
|
||||
|
||||
`exitOnCtrlC: true` calls `renderer.destroy()` when the user presses Ctrl+C. The code that creates the renderer must
|
||||
call `renderer.destroy()` on every other shutdown path.
|
||||
|
||||
Install the package:
|
||||
|
||||
```bash
|
||||
bun add @opentui/core
|
||||
```
|
||||
|
||||
Then build your first app with the [quickstart](https://opentui.com/docs/getting-started/quickstart).
|
||||
|
||||
## Runtime and platform support
|
||||
|
||||
`@opentui/core` runs on Bun 1.3.0 or later, or on Node.js 26.4.0 or later with ECMAScript modules (ESM) and
|
||||
`--experimental-ffi`.
|
||||
|
||||
The native ABI and the generated platform packages, such as `@opentui/core-linux-x64`, are internal distribution
|
||||
surfaces, not application APIs.
|
||||
|
||||
## AI agent skill
|
||||
|
||||
Install the OpenTUI documentation as a skill for your AI coding assistant with [`npx skills`](https://skills.sh):
|
||||
|
||||
```bash
|
||||
npx skills add anomalyco/opentui --skill opentui
|
||||
```
|
||||
|
||||
Add `-g` to install the skill globally.
|
||||
|
||||
## License
|
||||
|
||||
OpenTUI is licensed under the [MIT License](https://github.com/anomalyco/opentui/blob/main/LICENSE).
|
||||
@@ -1,154 +0,0 @@
|
||||
# Development Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Bun](https://bun.sh) - JavaScript runtime and package manager
|
||||
- [Zig](https://ziglang.org/learn/getting-started/) - Required for building native modules
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
git clone https://github.com/anomalyco/opentui.git
|
||||
cd opentui
|
||||
bun install
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
```bash
|
||||
bun run build
|
||||
```
|
||||
|
||||
**Note:** Only needed when changing native Zig code. TypeScript changes don't require rebuilding.
|
||||
|
||||
## Running Examples
|
||||
|
||||
```bash
|
||||
cd packages/examples
|
||||
bun run dev
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Build native dependencies first
|
||||
bun run build
|
||||
|
||||
# TypeScript tests
|
||||
cd packages/core
|
||||
bun test
|
||||
|
||||
# Native tests
|
||||
bun run test:native
|
||||
|
||||
# Filter native tests
|
||||
bun run test:native -Dtest-filter="test name"
|
||||
|
||||
# Benchmarks
|
||||
bun run bench:native
|
||||
```
|
||||
|
||||
The Zig implementation, tests, and benchmarks live in `packages/native`. Run direct Zig commands and the no-JavaScript
|
||||
example from that package:
|
||||
|
||||
```bash
|
||||
cd packages/native
|
||||
zig build test --summary all
|
||||
cd examples/hello
|
||||
zig build run
|
||||
```
|
||||
|
||||
## Local Development Linking
|
||||
|
||||
Link your local OpenTUI to another project:
|
||||
|
||||
```bash
|
||||
./scripts/link-opentui-dev.sh /path/to/your/project
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--react` - Also link `@opentui/react` and React dependencies
|
||||
- `--solid` - Also link `@opentui/solid` and SolidJS dependencies
|
||||
- `--dist` - Link built `dist` directories instead of source
|
||||
- `--copy` - Copy instead of symlink (requires `--dist`)
|
||||
- `--subdeps` - Find and link packages that depend on opentui (e.g., `opentui-spinner`)
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Link core only
|
||||
./scripts/link-opentui-dev.sh /path/to/your/project
|
||||
|
||||
# Link core and solid with subdependency discovery
|
||||
./scripts/link-opentui-dev.sh /path/to/your/project --solid --subdeps
|
||||
|
||||
# Link built artifacts
|
||||
./scripts/link-opentui-dev.sh /path/to/your/project --react --dist
|
||||
|
||||
# Copy for Docker/Windows
|
||||
./scripts/link-opentui-dev.sh /path/to/your/project --dist --copy
|
||||
```
|
||||
|
||||
The script automatically links:
|
||||
|
||||
- Main packages: `@opentui/core`, `@opentui/solid`, `@opentui/react`
|
||||
- Peer dependencies: `solid-js`, `react`, `react-dom`, `react-reconciler`
|
||||
- Subdependencies (with `--subdeps`): Packages like `opentui-spinner` that depend on opentui
|
||||
|
||||
**Requirements:** Target project must have `node_modules` (run `bun install` first).
|
||||
|
||||
## Debugging
|
||||
|
||||
OpenTUI captures `console.log` output. Toggle the built-in console with backtick or use [Environment Variables](https://opentui.com/docs/reference/env-vars) for debugging.
|
||||
|
||||
## Terminal Compatibility
|
||||
|
||||
### OSC 66 Artifacts on Older Terminals
|
||||
|
||||
**Problem:** If you see weird artifacts containing "66" in your terminal when running OpenTUI applications, your terminal emulator doesn't support OSC 66 escape sequences (used for explicit character width detection).
|
||||
|
||||
**Affected Terminals:**
|
||||
|
||||
- GNOME Terminal
|
||||
- Konsole (older versions)
|
||||
- xterm (older versions)
|
||||
- Many VT100/VT220 emulators
|
||||
|
||||
**Solution:** Disable OSC 66 queries by setting an environment variable:
|
||||
|
||||
```bash
|
||||
export OPENTUI_FORCE_EXPLICIT_WIDTH=false
|
||||
```
|
||||
|
||||
Or run your application with:
|
||||
|
||||
```bash
|
||||
OPENTUI_FORCE_EXPLICIT_WIDTH=false your-app
|
||||
```
|
||||
|
||||
**For Application Developers:**
|
||||
|
||||
Set it in your code before creating the renderer:
|
||||
|
||||
```typescript
|
||||
process.env.OPENTUI_FORCE_EXPLICIT_WIDTH = "false"
|
||||
|
||||
const renderer = new CliRenderer()
|
||||
// ... rest of your app
|
||||
```
|
||||
|
||||
Or add to your `.env` file:
|
||||
|
||||
```bash
|
||||
OPENTUI_FORCE_EXPLICIT_WIDTH=false
|
||||
```
|
||||
|
||||
**What This Does:**
|
||||
|
||||
- Prevents OSC 66 detection queries from being sent
|
||||
- Disables the explicit width feature
|
||||
- Falls back to standard width calculation
|
||||
- No visual artifacts on unsupported terminals
|
||||
|
||||
**Modern Terminals:** If your terminal supports OSC 66 (Kitty, Ghostty, WezTerm, Alacritty, iTerm2), you don't need this setting - they work correctly by default.
|
||||
@@ -0,0 +1,15 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 27 6" width="270" height="60" shape-rendering="crispEdges" role="img">
|
||||
<title>OpenTUI logo</title>
|
||||
<style>
|
||||
.logo-mark {
|
||||
fill: #000000;
|
||||
}
|
||||
|
||||
@media (prefers-color-scheme: dark) {
|
||||
.logo-mark {
|
||||
fill: #ffffff;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
<path class="logo-mark" d="M17 0h1v1h-1zM1 1h3v1h-3zM5 1h3v1h-3zM9 1h3v1h-3zM13 1h2v1h-2zM17 1h3v1h-3zM21 1h1v1h-1zM23 1h1v1h-1zM25 1h1v1h-1zM1 2h1v1h-1zM3 2h1v1h-1zM5 2h1v1h-1zM7 2h1v1h-1zM9 2h1v1h-1zM11 2h1v1h-1zM13 2h1v1h-1zM15 2h1v1h-1zM17 2h1v1h-1zM21 2h1v1h-1zM23 2h1v1h-1zM25 2h1v1h-1zM1 3h1v1h-1zM3 3h1v1h-1zM5 3h1v1h-1zM7 3h1v1h-1zM9 3h1v1h-1zM13 3h1v1h-1zM15 3h1v1h-1zM17 3h1v1h-1zM19 3h1v1h-1zM21 3h1v1h-1zM23 3h1v1h-1zM25 3h1v1h-1zM1 4h3v1h-3zM5 4h3v1h-3zM9 4h3v1h-3zM13 4h1v1h-1zM15 4h1v1h-1zM17 4h3v1h-3zM21 4h3v1h-3zM25 4h1v1h-1zM5 5h1v1h-1z" />
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 888 B |
Reference in new issue
Block a user