boba

README

boba - browser-oriented bubbletea adapter

boba is a Golang module that facilitates embedding BubbleTea Terminal User Interfaces (TUIs) into a Web Browser.

Installation

Go (server-side library and CLI tools):

go get github.com/btwiuse/boba

How and What?

The primary enabling technologies of this are:

• BubbleTea - Terminal UI framework for Go
• WebAssembly - For running Go code in browsers

Embedding a BubbleTea Application in a Web Browser

We can take entire BubbleTea applications and embed them into a Web Browser. The primary limitation is that all of its dependencies can also be compiled to WebAssembly.

Quickstart

The top-level boba.Run picks the right runtime for the build target, so a single main.go works for both the native terminal and the browser:

package main

import (
    "log"

    boba "github.com/btwiuse/boba"
)

func main() {
    if err := boba.Run(initialModel()); err != nil {
        log.Fatal(err)
    }
}

For easier porting from Bubble Tea — or when you need the program handle for Send, Quit, etc. — use boba.NewProgram:

func main() {
    bp := boba.NewProgram(initialModel())
    if _, err := bp.Run(); err != nil {
        log.Fatal(err)
    }
}

Build and run natively with go run ./cmd/myapp. Build for the browser with go run github.com/btwiuse/boba/cmd/boba-wasm-build -o web/app.wasm ./cmd/myapp/.

For finer control, the wasm subpackage exposes the browser bridge directly, and native code can construct a tea.Program the usual way.

Credits

• https://github.com/charmbracelet/bubbletea
• https://github.com/tmc/bubbweb
  • https://github.com/myka0/bubbweb-v2
• https://github.com/NimbleMarkets/go-booba
• https://github.com/BigJk/bubbletea-in-wasm

Documentation

Overview

Package boba provides a platform-polymorphic entry point for running BubbleTea programs that target both native terminals and web browsers.

The same main.go works on both targets: when compiled for a native platform, Run runs the model with a standard tea.Program; when compiled with GOOS=js GOARCH=wasm, Run installs the JavaScript bridge that boba's web terminal uses.

package main

import (
    "log"

    boba "github.com/btwiuse/boba"
)

func main() {
    if err := boba.Run(initialModel()); err != nil {
        log.Fatal(err)
    }
}

For finer control — or to match the original Bubble Tea API during porting — use NewProgram:

bp := boba.NewProgram(initialModel())
if _, err := bp.Run(); err != nil {
    log.Fatal(err)
}

For more granular control, subpackages are available:

• github.com/btwiuse/boba/wasm exposes the browser bridge directly.
• github.com/btwiuse/boba/serve runs a BubbleTea program as an HTTP/WebSocket/WebTransport backend for browser clients.

Index

• Variables
• func Run(model tea.Model, opts ...tea.ProgramOption) error
• type Program

Variables

var NewProgram = tea.NewProgram

NewProgram creates a new BubbleTea program for the native terminal.

Functions

func Run

func Run(model tea.Model, opts ...tea.ProgramOption) error

Run executes the given BubbleTea model with the appropriate runtime for the build target.

Types

type Program

type Program interface {
	Kill()
	Printf(template string, args ...any)
	Println(args ...any)
	Quit()
	ReleaseTerminal() error
	RestoreTerminal() error
	Run() (tea.Model, error)
	Send(msg tea.Msg)
	Wait()
}

Program provides an abstraction over wasm.Program and tea.Program