bubbweb

README

bubbweb

BubbWeb is a library for running Bubbletea terminal user interfaces in WebAssembly.

Live Demo

Check out the live demo to see BubbWeb in action.

Features

• Run Bubbletea TUIs directly in the browser
• Uses xterm.js for terminal emulation
• Handles input/output between JavaScript and Go
• Full mouse support (clicks, movement, wheel scrolling)
• Manages terminal resize events
• Includes ETag-based caching for efficient updates

Usage

import (
    tea "github.com/charmbracelet/bubbletea"
    "github.com/tmc/bubbweb"
)

func main() {
    // Create your BubbleTea model as usual
    model := yourModel()

    // Use bubbweb to run the program in WebAssembly
    prog := bubbweb.NewProgram(model, tea.WithAltScreen())
    if _, err := prog.Run(); err != nil {
        // Handle error
    }
}

Building a WebAssembly Application

# Build everything with go generate
go generate

# For local testing with auto-reload
cd example
go run github.com/tmc/serve@latest # or any other HTTP server

Then open http://localhost:8080 in your browser.

Example

See the example directory for a complete example including:

• A multi-pane text editor built with Bubbletea
• HTML/JavaScript integration with xterm.js
• Update notification system
• ETag-based caching for efficient updates

Deployment

This project can be easily deployed on GitHub Pages:

1. Push the example directory to your GitHub repository
2. Go to repository Settings → Pages
3. Set the source to the branch containing your example directory
4. Configure the root directory to / or /example depending on your repository structure
5. Save the settings and GitHub Pages will deploy your application

Your Bubbletea WebAssembly application will be available at https://[username].github.io/[repository]/example

Implementation Notes

BubbWeb handles several challenges of running Bubbletea in WebAssembly:

1. Provides custom I/O implementation for WebAssembly
2. Exposes JavaScript functions for browser communication:
   • bubbletea_write: Sends input from JavaScript to the Go program
   • bubbletea_read: Reads output from the Go program
   • bubbletea_resize: Sends terminal resize events to the Go program
   • bubbletea_mouse: Sends mouse events to the Go program
3. Enables full mouse support with standard BubbleTea event handling
4. Uses replacements for packages that don't fully support WebAssembly

Mouse Support

Mouse events are translated from browser events to BubbleTea's mouse event system:

case tea.MouseMsg:
    switch msg.Type {
    case tea.MousePress:
        // Handle mouse press at (msg.X, msg.Y)
    case tea.MouseRelease:
        // Handle mouse release
    case tea.MouseMotion:
        // Handle mouse movement
    case tea.MouseWheelUp, tea.MouseWheelDown:
        // Handle scrolling
    }
}

The coordinates are automatically converted from pixel coordinates to terminal cell coordinates.

License

MIT

Documentation

Overview

Package bubbweb provides a WebAssembly interface for BubbleTea applications.

BubblTea is a Go framework for building terminal user interfaces. With bubbweb, these terminal UIs can be compiled to WebAssembly and run in a browser using a terminal emulator like xterm.js.

Basic usage:

import (
	tea "github.com/charmbracelet/bubbletea"
	"github.com/tmc/bubbweb"
)

func main() {
	// Create your BubbleTea model as usual
	model := yourModel()

	// Use bubbweb to run the program in WebAssembly
	prog := bubbweb.NewProgram(model, tea.WithAltScreen())
	if _, err := prog.Run(); err != nil {
		// Handle error
	}
}

When compiled to WebAssembly, the program provides JavaScript bindings that connect to an xterm.js terminal in the browser. The included example demonstrates the complete setup, including HTML and JavaScript.

The bubbweb package handles input and output between the BubbleTea application and the browser. It exposes four JavaScript functions:

• bubbletea_write: Sends input from JavaScript to the Go program
• bubbletea_read: Reads output from the Go program
• bubbletea_resize: Sends terminal resize events to the Go program
• bubbletea_mouse: Sends mouse events to the Go program

Mouse support is enabled by default and works with standard BubbleTea mouse handling. Your application will receive mouse events through the tea.MouseMsg type:

case tea.MouseMsg:
    switch msg.Type {
    case tea.MousePress:
        // Handle mouse press
    case tea.MouseRelease:
        // Handle mouse release
    case tea.MouseMotion:
        // Handle mouse movement
    case tea.MouseWheelUp, tea.MouseWheelDown:
        // Handle scrolling
    }

These JavaScript functions are called by the JavaScript code in the HTML page.

To build a WebAssembly application using bubbweb:

1. Create a Go program that uses bubbweb
2. Compile it with GOOS=js GOARCH=wasm
3. Copy wasm_exec.js from Go distribution
4. Create HTML with xterm.js that loads and communicates with the WebAssembly module
5. Configure xterm.js to forward mouse events to the WebAssembly module

See the example directory for a complete implementation.

Index

• Variables

Variables

var NewProgram = tea.NewProgram