github.com/dsisnero/bubbletea.cr

Crystal port of Go's bubbletea TUI framework
Terminal user interfaces based on The Elm Architecture

Architecture · Development · Guidelines · Testing · PR Workflow · Porting Parity · Upgrade Guide v2

---

Bubble Tea is a refreshing drink with layers of flavor; this framework layers terminal UI components into elegant applications. Just as bubble tea combines tea, milk, and tapioca pearls into a harmonious drink, this framework combines models, updates, and views into cohesive terminal interfaces.

---

Quick Start

1. Add to your shard.yml:

   dependencies:
     bubbletea:
       github: dsisnero/bubbletea

2. Install:

   shards install

3. Use in your code:

   require "bubbletea"
   
   # See bubbletea-examples/ for ported examples

Features

• Elm Architecture: Model-Update-View pattern for terminal UIs
• Exact Go parity: Direct port maintaining identical behavior
• Command system: Side effects wrapped in Cmd objects
• Event handling: Keyboard, mouse, and custom events
• Terminal rendering: Efficient screen updates and cursor management

Development

make install   # Install dependencies
make test      # Run specs
make format    # Format Crystal code
make lint      # Run Crystal linter
rumdl fmt docs/ *.md  # Format markdown documentation

See Development Guide for full setup instructions.

Documentation

Document	Purpose
Architecture	System design and data flow
Development	Setup and daily workflow
Coding Guidelines	Code style and conventions
Testing	Test commands and patterns
PR Workflow	Commits, PRs, and review process
Porting Parity	Upstream source tracking
Upgrade Guide v2	Migration from v1 to v2

Contributing

1. Create an issue: /forge-create-issue
2. Implement: /forge-implement-issue <number>
3. Self-review: /forge-reflect-pr
4. Address feedback: /forge-address-pr-feedback
5. Update changelog: /forge-update-changelog