DOCSEARCHbyAlgolia
Submit Docs

Bubble Tea App Template

repository·main·Indexed 42 days ago

https://github.com/charmbracelet/bubbletea-app-template

A boilerplate template for developing terminal applications using the Bubble Tea framework and Charm ecosystem. It includes pre-configured core libraries such as bubbletea, bubbles, and lipgloss, along with GitHub Actions workflows, GoReleaser, and golangci-lint for CI/CD.

Tokens
796
Snippets
3
Records
5
Agent score
4%

What's inside Bubble Tea App Template

  1. Use the bubbletea-app-template to create Bubble Tea apps

    main
    This template repository provides a starting point for building terminal applications using the Charm ecosystem. It includes a sample application that integrates the core dependencies required for most Bubble Tea projects, allowing you to immediately begin building UI components and terminal logic.

  2. Implement a Bubble Tea application structure

    main

    To build a Bubble Tea application, you must implement the tea.Model interface, which requires three core methods: Init, Update, and View.

    1. Init(): Returns an initial tea.Cmd to perform startup tasks (e.g., starting a spinner or fetching data).
    2. Update(tea.Msg): Handles incoming messages (key presses, timer ticks, custom errors). It returns the updated model and an optional tea.Cmd to trigger further actions.
    3. View(): Returns a string representing the current state of the UI to be rendered in the terminal.

    In the Update method, you typically use a type switch to handle different message types like tea.KeyMsg or custom error types.

    type model struct {
	spinner  spinner.Model
	quitting bool
	err      error
}

func (m model) Init() tea.Cmd {
	return m.spinner.Tick
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.KeyMsg:
		// handle keys
	case errMsg:
		// handle errors
	default:
		// handle other messages
	}
	return m, nil
}

func (m model) View() string {
	return "rendered UI string"
}

  3. Review included dependencies and tooling

    main

    The template comes pre-configured with the following core libraries and DevOps tooling:

    Core Libraries:

    • bubbletea: The framework for building terminal user interfaces.
    • bubbles: A collection of common UI components (widgets).
    • lipgloss: A library for styling terminal text and layouts.

    DevOps & CI/CD:

    • GitHub Actions workflows for build, test, lint, and release.
    • GoReleaser configurations for automated binary releases.
    • golangci-lint configurations for code quality enforcement.

  4. Define key bindings with bubbles/key

    main

    Use key.NewBinding to define reusable key sequences and help text. This allows you to check for multiple keys (like q, esc, or ctrl+c) using key.Matches within your Update loop.

    var quitKeys = key.NewBinding(
	key.WithKeys("q", "esc", "ctrl+c"),
	key.WithHelp("", "press q to quit"),
)

  5. Run a Bubble Tea program in main()

    main

    To start the application loop, use tea.NewProgram with your initial model and call p.Run(). This starts the event loop and handles the terminal rendering.

    func main() {
	p := tea.NewProgram(initialModel())
	if _, err := p.Run(); err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
}