An ExRatatui app can be an Erlang or Gleam module. There is no separate API: the module implements the ExRatatui.App callbacks and starts through ExRatatui.App.start_link/2. Elixir still has to be installed, because ExRatatui is a Mix project.

Runnable versions of everything here are in the catalog: examples/gleam/counter and examples/erlang/counter.

Installing

Gleam

Needs gleam, elixir, and rebar3 on the PATH. Gleam builds ExRatatui with Mix and telemetry with rebar3.

gleam add ex_ratatui

Gleam rejects a Mix project as a path or git dependency, so only Hex releases work.

Erlang

Needs rebar3 and elixir. Use the exerl plugin. rebar_mix copies only a dependency's ebin, which loses the NIF, so the app fails to load it at runtime.

{deps, [{ex_ratatui, "~> 0.20"}]}.
{plugins, [exerl]}.

Elixir's lib dir has to be on ERL_LIBS, or Application.app_dir/2 is undefined when the NIF loads:

export ERL_LIBS=$(elixir -e 'IO.puts(Path.dirname(:code.lib_dir(:elixir)))')

The smallest app

Erlang

-module(my_tui).
-behaviour('Elixir.ExRatatui.App').
-export([start/0, mount/1, render/2, handle_event/2]).

start() ->
    {ok, Pid} = 'Elixir.ExRatatui.App':start_link(?MODULE, []),
    Ref = monitor(process, Pid),
    receive {'DOWN', Ref, process, Pid, _Reason} -> ok end.

mount(_Opts) ->
    {ok, 0}.

render(Count, #{width := Width, height := Height}) ->
    Text = <<"Counter: ", (integer_to_binary(Count))/binary>>,
    Paragraph = 'Elixir.ExRatatui.Widgets.Paragraph':'__struct__'(#{text => Text}),
    Area = 'Elixir.ExRatatui.Layout.Rect':'__struct__'(#{x => 0, y => 0, width => Width, height => Height}),
    [{Paragraph, Area}].

handle_event(#{code := <<"q">>}, Count) -> {stop, Count};
handle_event(#{code := <<"k">>}, Count) -> {noreply, Count + 1};
handle_event(_Event, Count) -> {noreply, Count}.
rebar3 shell --eval 'my_tui:start(), init:stop().'

rebar3 shell --eval exits without evaluating when stdin isn't a terminal. For scripts and CI, run rebar3 compile and then erl -noshell -pa _build/default/lib/*/ebin -eval '...'.

Gleam

Gleam can't write Elixir structs, so a small Erlang file sits next to the module in src/.

import gleam/dynamic.{type Dynamic}
import gleam/int

pub type Next {
  Noreply(Int)
  Stop(Int)
}

pub type AppModule {
  MyTui
}

pub type Pid

pub type Event

pub type Frame

pub type Rect

pub type Widget

pub fn mount(_options: Dynamic) -> Result(Int, Nil) {
  Ok(0)
}

pub fn render(count: Int, frame: Frame) -> List(#(Widget, Rect)) {
  [#(paragraph("Counter: " <> int.to_string(count)), area(frame))]
}

pub fn handle_event(event: Event, count: Int) -> Next {
  case key_code(event) {
    "q" -> Stop(count)
    "k" -> Noreply(count + 1)
    _ -> Noreply(count)
  }
}

pub fn main() -> Nil {
  let assert Ok(pid) = start_link(MyTui, [])
  wait_for_exit(pid)
}

@external(erlang, "Elixir.ExRatatui.App", "start_link")
fn start_link(module: AppModule, options: List(Dynamic)) -> Result(Pid, Dynamic)

@external(erlang, "my_tui_ffi", "paragraph")
fn paragraph(text: String) -> Widget

@external(erlang, "my_tui_ffi", "area")
fn area(frame: Frame) -> Rect

@external(erlang, "my_tui_ffi", "key_code")
fn key_code(event: Event) -> String

@external(erlang, "my_tui_ffi", "wait_for_exit")
fn wait_for_exit(pid: Pid) -> Nil
-module(my_tui_ffi).
-export([paragraph/1, area/1, key_code/1, wait_for_exit/1]).

paragraph(Text) ->
    'Elixir.ExRatatui.Widgets.Paragraph':'__struct__'(#{text => Text}).

area(#{width := Width, height := Height}) ->
    'Elixir.ExRatatui.Layout.Rect':'__struct__'(#{x => 0, y => 0, width => Width, height => Height}).

key_code(#{code := Code}) -> Code;
key_code(_Event) -> <<>>.

%% `gleam run` halts the VM as soon as main returns.
wait_for_exit(Pid) ->
    Ref = monitor(process, Pid),
    receive {'DOWN', Ref, process, Pid, _Reason} -> nil end.

Data shapes

Elixir modules are the atoms 'Elixir.ExRatatui.Layout' and so on, and Elixir strings are binaries. In Gleam, @external(erlang, "Elixir.ExRatatui.Layout", "split") binds any function whose arguments Gleam can write.

ValueErlangGleam
Widgets, Rect, Style, Block'Elixir.ExRatatui.Style':'__struct__'(#{fg => cyan})The same, in the Erlang file
TextInput and Textarea state'Elixir.ExRatatui':text_input_new(), a reference kept in the stateThe same function, through @external
Frame, eventsMaps: #{width := W}, #{code := <<"q">>, kind := <<"press">>}Field access in the Erlang file
mount/1 result{ok, State}Ok(state)
Transition result{noreply, State}, {stop, State}Custom type: Noreply(state), Stop(state)
Runtime opts{noreply, State, [{'render?', false}]}In the Erlang file; a custom type can't name 'render?'
Start options[{test_mode, {80, 24}}, {name, nil}]Custom type: TestMode(#(80, 24)), Name(Nil)
Constraints{length, 3}, {min, 0}Custom type: Length(3), Min(0)
Colors, modifiers, bordersdark_gray, bold, allCustom type: DarkGray, Bold, All

Nested values have to be real structs too: a plain map for style or block raises when the frame is encoded.

The reducer style

In Elixir, use ExRatatui.App, runtime: :reducer only adds three callbacks that forward to init/1 and update/2. Without use, write them by hand and the module works like a reducer app:

mount(Opts) -> init(Opts).
handle_event(Event, Model) -> update({event, Event}, Model).
handle_info(Message, Model) -> update({info, Message}, Model).

subscriptions(_Model) ->
    ['Elixir.ExRatatui.Subscription':interval(counter_tick, 1000, tick)].

subscriptions/1 and runtime opts such as commands work the same. The only difference is mode: :callbacks in ExRatatui.Runtime.snapshot/1.

handle_info/2 receives whatever reaches the runtime's mailbox, so a Gleam version needs a catch-all clause even if its message type lists only Tick.

Supervision

ExRatatui.App.child_spec/2 returns a map an OTP supervisor accepts:

init([]) ->
    Children = ['Elixir.ExRatatui.App':child_spec(my_tui, [])],
    {ok, {#{strategy => one_for_one}, Children}}.

A gleam_otp supervisor takes a function that returns actor.Started, so wrap start_link/2, with Pid from gleam/erlang/process in its @external. Make the child Transient like child_spec/2 does: the default Permanent restarts the app when it quits on q.

import gleam/otp/actor
import gleam/otp/static_supervisor as supervisor
import gleam/otp/supervision
import gleam/string

fn start_tui() -> Result(actor.Started(Nil), actor.StartError) {
  case start_link(MyTui, []) {
    Ok(pid) -> Ok(actor.Started(pid:, data: Nil))
    Error(reason) -> Error(actor.InitFailed(string.inspect(reason)))
  }
}

pub fn start_supervisor() {
  supervisor.new(supervisor.OneForOne)
  |> supervisor.add(
    supervision.worker(start_tui) |> supervision.restart(supervision.Transient),
  )
  |> supervisor.start
}

Transports

transport: :ssh and transport: :distributed work from both languages with the options in the SSH and distribution guides, and 'Elixir.ExRatatui.Distributed':attach(Node, my_tui) attaches from an Erlang client.

The SSH daemon needs the ssh application running, which comes with starting ex_ratatui. gleam run starts dependencies on its own, while a plain erl -eval has to call application:ensure_all_started(ex_ratatui).

Testing

test_mode and ExRatatui.Runtime.inject_event/2 work as in the Testing guide. Both examples have a suite that drives the app this way: an EUnit one run with rebar3 eunit, and a gleam test one that goes through a small Erlang file of its own.

Limits

  • No custom widgets. ExRatatui.Widget is an Elixir protocol, and neither language can write a defimpl.
  • No JavaScript target for Gleam. ExRatatui is a NIF on the BEAM.
  • Gleam can't check the callbacks. Erlang's -behaviour warns about a missing callback at compile time. Gleam has no behaviours and trusts @external types as written, so a misspelled callback or a wrong signature only fails at runtime.
  • A wrong shim can look like a blank screen. A bad widget doesn't crash the app: the frame is dropped with a log line and a [:ex_ratatui, :render, :dropped] telemetry event, and the last good frame stays up.
  • Gleam types. Every widget needs a shim in an Erlang file today. A separate package with typed widgets and events would remove them.