github.com/tmc/bubbweb

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:

• Push the example directory to your GitHub repository
• Go to repository Settings → Pages
• Set the source to the branch containing your example directory
• Configure the root directory to / or /example depending on your repository structure
• 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:

• Provides custom I/O implementation for WebAssembly
• 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
• Enables full mouse support with standard BubbleTea event handling
• 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