[go-fan] Go Module Review: bubbletea

[github-actions[bot]]

🐹 Bubble Tea is the TUI framework powering gh-aw's interactive spinner and list selector. Today's review covers the current v1.3.10 usage, the recently-released v2.0.1 (2026-03-02), and concrete improvement opportunities in the existing code.

Module Overview

github.com/charmbracelet/bubbletea is the Go TUI framework based on the Elm Architecture. Models implement Init() Cmd, Update(Msg) (Model, Cmd), and View() string. It drives gh-aw's spinner animations and interactive list selection.

Current Usage in gh-aw

• Files: 2 (pkg/console/list.go, pkg/console/spinner.go)
• Version in use: v1.3.10 (latest: v2.0.1 at charm.land/bubbletea/v2)
• Key APIs used: tea.NewProgram, tea.WithAltScreen(), tea.WithoutRenderer(), tea.WithOutput(), program.Run(), program.Quit(), program.Send()

The spinner uses tea.WithoutRenderer() for manual ANSI output to stderr — a valid pattern for inline spinners. The list uses tea.WithAltScreen() for full-screen interactive selection with a TTY fallback.

Research Findings

Recent Updates (v2.0.0 + v2.0.1, Feb–Mar 2026)

The v2 release is a substantial upgrade with a new import domain and several API changes:

• New import path: charm.land/bubbletea/v2 (no longer github.com/charmbracelet/bubbletea)
• Declarative View(): Returns tea.View struct instead of string. Terminal features are now set declaratively (v.AltScreen = true) rather than as constructor options
• Cursed Renderer: New ncurses-inspired renderer with synchronized output (mode 2026) for flicker-free updates
• tea.KeyPressMsg / tea.KeyReleaseMsg: tea.KeyMsg now matches both; enables shift+enter, ctrl+h, key-release events
• tea.WithWindowSize(w, h): Sets window dimensions for non-TTY testing — no more mocking
• Auto TTY input: v2 always opens the TTY for input by default, fixing stdout-is-piped edge cases
• Built-in color downsampling: Automatically adapts 24-bit colors to the terminal's profile
• Background color detection: tea.RequestBackgroundColor / tea.BackgroundColorMsg for adaptive light/dark theming

Best Practices from Maintainers

• Use v.AltScreen = true in View() rather than constructor options (v2)
• Use tea.WithWindowSize() in tests to avoid real-TTY requirements
• Prefer tea.RequestBackgroundColor + tea.BackgroundColorMsg for adaptive color styling

Improvement Opportunities

🏃 Quick Wins

1. Fix WindowSizeMsg height handling (list.go:48–50)

   Currently only width is updated on resize:

   case tea.WindowSizeMsg:
       m.list.SetWidth(msg.Width)  // ← height is never updated!
       return m, nil

   Should also set height so the list uses the full terminal on resize:

   case tea.WindowSizeMsg:
       m.list.SetSize(msg.Width, msg.Height)
       return m, nil

2. Safe type assertion (list.go:183)

   // Current — will panic if model type changes
   result := finalModel.(listModel)
   
   // Better
   result, ok := finalModel.(listModel)
   if !ok { return "", errors.New("unexpected model type") }

3. Add tea.WithOutput(os.Stderr) to list program (list.go:174)

   The spinner correctly targets stderr. The list program uses default stdout, but TTY detection in the same file checks stderr. These should be consistent:

   p := tea.NewProgram(m, tea.WithAltScreen(), tea.WithOutput(os.Stderr))

✨ Feature Opportunities

4. Detect terminal size for initial list dimensions (list.go:154)

   The list is initialized with hardcoded 80×20:

   l := list.New(listItems, delegate, 80, 20)

   Using golang.org/x/term (already a direct dependency) to detect actual terminal dimensions would give a better initial fit. The WindowSizeMsg will still correct it, but the first frame would look right.

5. tea.WithWindowSize() in tests (v2 feature)

   Once on v2, tests can specify a window size without needing a real TTY:

   p := tea.NewProgram(model, tea.WithWindowSize(80, 24))

   This would enable more thorough unit tests of list rendering.

6. Adaptive light/dark styling (v2 BackgroundColorMsg)

   The list delegate hardcodes dark-biased colors. With v2, tea.RequestBackgroundColor returns a BackgroundColorMsg that exposes IsDark() — enabling proper adaptive styling.

📐 Best Practice Alignment

7. v2 Migration Roadmap

   The current code is v1 idiomatic and correct. The v2 migration would require:

   Change	Files affected
   Import path → charm.land/bubbletea/v2	list.go, spinner.go
   View() string → View() tea.View	listModel, spinnerModel
   tea.KeyMsg → tea.KeyPressMsg	list.go:37, spinner.go:75
   tea.WithAltScreen() → v.AltScreen = true	list.go:174

   The migration is mechanical and low-risk. The biggest benefit is the Cursed Renderer (better performance, no flicker) and tea.WithWindowSize() for testing.

Recommendations

Priority	Action
High	Fix WindowSizeMsg to also update height in list.go (list won't resize vertically otherwise)
High	Add tea.WithOutput(os.Stderr) to list program for output consistency
Medium	Fix unsafe type assertion to use comma-ok pattern
Medium	Detect terminal size for initial list dimensions
Low	Plan v2 migration for improved renderer and testing support

Next Steps

• Apply Quick Wins 1–3 (small, safe changes to list.go)
• Track v2 migration as a follow-up — bubbles v2.0.0 was also just released (2026-02-24) and is part of the same ecosystem upgrade

---

Module summary saved to: scratchpad/mods/bubbletea.md
Selected as most recently updated unreviewed direct dependency (v2.0.1 released 2026-03-02)

References:

• §22842632871

AI generated by Go Fan · history

• expires on Mar 10, 2026, 7:26 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-10T07:26:47.368Z.

Closed by Workflow