Home

async-template

DEPRECATED: Use https://github.com/ratatui-org/templates instead

cargo generate ratatui-org/templates async

Features

  • Uses tokio for async events
    • Start and stop key events to shell out to another TUI like vim
    • Supports suspend signal hooks
  • Logs using tracing
  • better-panic
  • color-eyre
  • human-panic
  • Clap for command line argument parsing
  • Component trait with Home and Fps components as examples

Usage

You can start by using cargo-generate:

cargo install cargo-generate
cargo generate --git https://github.com/ratatui-org/async-template --name ratatui-hello-world
cd ratatui-hello-world

You can also use a template.toml file to skip the prompts:

$ cargo generate --git https://github.com/ratatui-org/async-template --template-values-file .github/workflows/template.toml --name ratatui-hello-world
# OR generate from local clone
$ cargo generate --path . --template-values-file .github/workflows/template.toml --name ratatui-hello-world

Run

cargo run # Press `q` to exit

Show help

$ cargo run -- --help
Hello World project using ratatui-template

Usage: ratatui-hello-world [OPTIONS]

Options:
  -t, --tick-rate <FLOAT>   Tick rate, i.e. number of ticks per second [default: 1]
  -f, --frame-rate <FLOAT>  Frame rate, i.e. number of frames per second [default: 60]
  -h, --help                Print help
  -V, --version             Print version

Show version

Without direnv variables:

$ cargo run -- --version
    Finished dev [unoptimized + debuginfo] target(s) in 0.07s
     Running `target/debug/ratatui-hello-world --version`
ratatui-hello-world v0.1.0-47-eb0a31a

Authors: Dheepak Krishnamurthy

Config directory: /Users/kd/Library/Application Support/com.kdheepak.ratatui-hello-world
Data directory: /Users/kd/Library/Application Support/com.kdheepak.ratatui-hello-world

With direnv variables:

$ direnv allow
direnv: loading ~/gitrepos/async-template/ratatui-hello-world/.envrc
direnv: export +RATATUI_HELLO_WORLD_CONFIG +RATATUI_HELLO_WORLD_DATA +RATATUI_HELLO_WORLD_LOG_LEVEL

$ # OR

$ export RATATUI_HELLO_WORLD_CONFIG=`pwd`/.config
$ export RATATUI_HELLO_WORLD_DATA=`pwd`/.data
$ export RATATUI_HELLO_WORLD_LOG_LEVEL=debug

$ cargo run -- --version
    Finished dev [unoptimized + debuginfo] target(s) in 0.07s
     Running `target/debug/ratatui-hello-world --version`
ratatui-hello-world v0.1.0-47-eb0a31a

Authors: Dheepak Krishnamurthy

Config directory: /Users/kd/gitrepos/async-template/ratatui-hello-world/.config
Data directory: /Users/kd/gitrepos/async-template/ratatui-hello-world/.data

Documentation

Read documentation on design decisions in the template here: https://ratatui-org.github.io/async-template/

Counter + Text Input Demo

This repo contains a ratatui-counter folder that is a working demo as an example. If you wish to run a demo without using cargo generate, you can run the counter + text input demo by following the instructions below:

git clone https://github.com/ratatui-org/async-template
cd async-template
cd ratatui-counter # counter + text input demo

export RATATUI_COUNTER_CONFIG=`pwd`/.config
export RATATUI_COUNTER_DATA=`pwd`/.data
export RATATUI_COUNTER_LOG_LEVEL=debug
# OR
direnv allow

cargo run

You should see a demo like this:

Background

ratatui is a Rust library to build rich terminal user interfaces (TUIs) and dashboards. It is a community fork of the original tui-rs created to maintain and improve the project.

The source code of this project is an opinionated template for getting up and running with ratatui. You can pick and choose the pieces of this async-template to suit your needs and sensibilities. This rest of this documentation is a walk-through of why the code is structured the way it is, so that you are aided in modifying it as you require.

ratatui is based on the principle of immediate rendering with intermediate buffers. This means that at each new frame you have to build all widgets that are supposed to be part of the UI. In short, the ratatui library is largely handles just drawing to the terminal.

Additionally, the library does not provide any input handling nor any event system. The responsibility of getting keyboard input events, modifying the state of your application based on those events and figuring out which widgets best reflect the view of the state of your application is on you.

The ratatui-org project has added a template that covers the basics, and you find that here: https://github.com/ratatui-org/rust-tui-template.

I wanted to take another stab at a template, one that uses tokio and organizes the code a little differently. This is an opinionated view on how to organize a ratatui project.

Info

Since ratatui is a immediate mode rendering based library, there are multiple ways to organize your code, and there’s no real “right” answer. Choose whatever works best for you!

This project also adds commonly used dependencies like logging, command line arguments, configuration options, etc.

As part of this documentation, we’ll walk through some of the different ways you may choose to organize your code and project in order to build a functioning terminal user interface. You can pick and choose the parts you like.

You may also want to check out the following links (roughly in order of increasing complexity):