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() {
model := yourModel()
prog := bubbweb.NewProgram(model, tea.WithAltScreen())
if _, err := prog.Run(); err != nil {
}
}
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:
case tea.MouseRelease:
case tea.MouseMotion:
case tea.MouseWheelUp, tea.MouseWheelDown:
}
}
The coordinates are automatically converted from pixel coordinates to terminal cell coordinates.
License
MIT