Go Dashboard Development with Bubbletea

Expert guidance for building terminal-based dashboard applications using Go, Bubbletea (terminal UI framework), Lipgloss (styling), and Wire (dependency injection).

Code Style and Conventions

Follow these Go coding standards:

1. **Formatting**: Use `gofmt` for automatic formatting

2. **Linting**: Apply `golangci-lint` for code quality checks

3. **Constants**: Replace magic numbers with named constants

4. **Documentation**: Document all exported symbols (functions, types, variables)

5. **Line Length**: Keep lines under 100 characters

Widget-Specific Rules

Ensure all widgets comply with the `Widget` interface

Implement proper focus management patterns

Handle time values carefully:

- Check for zero time values

- Validate time pointers before use

- Use time comparison helpers

Architecture Patterns

Lifecycle Management

Use Bubbletea's built-in lifecycle system:

**Signal Handling**: Handle SIGINT and SIGTERM gracefully

**Key Events**: Respond to quit commands (`q`, `ctrl+c`, `d`)

**Cleanup Responsibilities**:

- Logger: Flush buffers on exit

- UI/Terminal: Let Bubbletea handle restoration

- Components: Use Init/Update methods for setup/teardown

- Widgets: Implement cleanup in Blur method

Dependency Injection

Use Wire for dependency management:

1. Define providers in `providers.go`

2. Define interfaces in `interfaces.go`

3. Generate code in `wire_gen.go`

4. Prefer constructor injection over field injection

5. Use interfaces for all external dependencies

Logging

Implement structured logging with uber-go/zap:

**Log Levels**: debug, info, warn, error

**Request Tracking**: Include request IDs in all logs

**Context-Based Tracking**: Use context for request correlation

**Testing Utilities**:

- `testutil.NewTestLogger` for test logger creation

- `testutil.ReadLogFile` to verify log output

- `testutil.VerifyLogContent` to validate log entries

**Important**: Do not use `fmt` package for output in dashboard code (except in tests, main.go, and logger package itself). Use the logger package instead.

UI Component Development

Model-View-Update Pattern

Build components using Bubbletea's architecture:

**Model**: State representation

**View**: Rendering logic

**Update**: State transitions based on messages

Widget System

Implement widgets with these features:

**Layout**: Support horizontal and vertical arrangements

**Focus**: Style components based on focus state

**Size Constraints**: Define minimum dimensions

**Dynamic Resizing**: Respond to terminal size changes

**Caching**: Cache styles and content for performance

Base Widget Responsibilities

Every widget should handle:

1. **Dimension Management**: SetSize, GetDimensions

2. **Focus State Management**: Focus, Blur, IsFocused

3. **Style Selection**: Apply appropriate styles based on state

4. **Default Command Handling**: Process standard keyboard events

Interface Segmentation

Define clear interfaces:

**Widget Interface**: Core methods (Init/Update/View)

**Focusable Interface**: Focus management (Focus/Blur/IsFocused)

**Sizable Interface**: Size management (SetSize/GetDimensions)

Use composition over inheritance for code reuse.

Component Design Principles

Follow SOLID principles:

**Single Responsibility**: Each component has one clear purpose

**DRY**: Don't Repeat Yourself - extract common patterns

**Interface Segregation**: Small, focused interfaces

Size Management

Define minimum size constraints

Handle dynamic resizing gracefully

Ensure content flows properly within dimensions

Validate size inputs (minimum dimensions, overflow protection)

Focus Handling

Maintain focus state

Display clear focus indicators

Support keyboard navigation between focusable elements

Performance Requirements

Target these metrics:

**View Rendering**: < 1ms per render

**Memory Allocations**: < 1KB per operation

**CPU Usage**: < 5% during normal operation

Optimization Strategies

Cache styles to avoid recalculation

Cache rendered content when possible

Implement partial updates instead of full re-renders

Cache size calculations

Testing Strategy

Test Categories

1. **Unit Tests**: Widget behavior, state transitions, message handling, style application

2. **Integration Tests**: Widget interactions, focus management, layout behavior, event propagation

3. **Benchmark Tests**: View rendering, update performance, memory allocations, style operations

Coverage Goals

Core logic: > 80%

UI components: > 70%

Integration paths: > 60%

Test Utilities

Use provided test helpers:

```go

// Create test logger

logger := testutil.NewTestLogger()

// Create UI test harness

uiTest := testutil.NewUITest()

// Verify log output

logs := testutil.ReadLogFile(logPath)

testutil.VerifyLogContent(logs, expectedContent)

```

**Important**: Use `testutil.NewTestLogger` instead of local `setupTestLogger` functions.

Error Handling

Return errors, never panic

Wrap errors with context using `fmt.Errorf("context: %w", err)`

Log errors with structured context

Provide user-friendly feedback in UI

Handle edge cases explicitly

Validate all inputs

File Organization

```

/cmd - Entry points

/internal - Private application code

/pkg - Public libraries

/docs - Documentation

/test - Test utilities

/scripts - Build and deployment scripts

/configs - Configuration files

```

Widget File Structure

```

components/widget.go - Widget interface definitions

widgets/{type}/widget.go - Widget implementations

styles/{widget}.go - Widget styles

widgets/{type}/widget_test.go - Widget tests

```

Documentation Requirements

Document all exported symbols with godoc comments

Provide package-level documentation

Include usage examples for complex features

For widgets, document:

- Interface requirements

- Size management behavior

- Focus handling patterns

- Update message patterns

Deprecation Handling

Always use the latest APIs

Update code when deprecation notices appear

Document temporary use of deprecated APIs with TODO comments

Example: Use `p.Run()` instead of deprecated `p.Start()` for Bubbletea programs

Linting Rules

Custom Rules

**No fmt package**: Use logger package for output (except tests, main.go, logger package)

**Use testutil**: Replace local `setupTestLogger` with `testutil.NewTestLogger`

**Widget interface**: All widgets must implement the full Widget interface

Example Widget Implementation

```go

// Widget interface compliance

type MyWidget struct {

base.Widget

// widget fields

}

// Implement required methods

func (w *MyWidget) Init() tea.Cmd { /* ... */ }

func (w *MyWidget) Update(msg tea.Msg) (tea.Model, tea.Cmd) { /* ... */ }

func (w *MyWidget) View() string { /* ... */ }

// Implement Focusable

func (w *MyWidget) Focus() { /* ... */ }

func (w *MyWidget) Blur() { /* cleanup */ }

func (w *MyWidget) IsFocused() bool { /* ... */ }

// Implement Sizable

func (w *MyWidget) SetSize(width, height int) { /* validate and store */ }

func (w *MyWidget) GetDimensions() (int, int) { /* return dimensions */ }

```

Key Constraints

All widgets must implement Widget, Focusable, and Sizable interfaces

Use Wire for dependency injection

Use zap for logging (not fmt)

Target sub-millisecond rendering performance

Maintain > 70% test coverage for UI components

Document all exported APIs

Go Dashboard Development with Bubbletea

Go Dashboard Development with Bubbletea

Code Style and Conventions

Widget-Specific Rules

Architecture Patterns

Lifecycle Management

Dependency Injection

Logging

UI Component Development

Model-View-Update Pattern

Widget System

Base Widget Responsibilities

Interface Segmentation

Component Design Principles

Size Management

Focus Handling

Performance Requirements

Optimization Strategies

Testing Strategy

Test Categories

Coverage Goals

Test Utilities

Error Handling

File Organization

Widget File Structure

Documentation Requirements

Deprecation Handling

Linting Rules

Custom Rules

Example Widget Implementation

Key Constraints

Reviews (0)