Development rules for building terminal dashboards with Go, Bubbletea, and Lipgloss. Includes widget architecture, lifecycle management, dependency injection with Wire, structured logging, and performance optimization patterns.
Development rules for building terminal-based dashboards using Go, Bubbletea, and Lipgloss with a focus on widget architecture, lifecycle management, and performance optimization.
Follow standard Go conventions and best practices:
1. **Formatting & Linting**
- Use `gofmt` for automatic formatting
- Use `golangci-lint` for static analysis
- Document all exported symbols with clear godoc comments
- Keep line length under 100 characters
2. **Constants & Magic Numbers**
- Replace magic numbers with named constants
- Use descriptive constant names that explain intent
3. **Widget Interface Compliance**
- All widgets must implement the full Widget interface
- Follow established widget interface patterns
- Ensure proper focus management in all focusable widgets
4. **Time Handling**
- Always check for zero time values before use
- Validate time pointers are not nil
- Use time comparison helpers instead of direct comparisons
Use Bubbletea's built-in lifecycle management system:
1. **Signal Handling**
- Handle SIGINT and SIGTERM gracefully
- Support keyboard shortcuts: `q`, `ctrl+c`, `d` for exit
2. **Cleanup Responsibilities**
- Logger: Flush logs on exit
- UI: Handled automatically by Bubbletea
- Terminal: Restored automatically by Bubbletea
- Components: Use `Init` for setup and `Update` for teardown
- Widgets: Implement proper cleanup in `Blur` method
3. **Program Lifecycle**
- Use `p.Run()` instead of deprecated `p.Start()`
- Initialize all components in `Init` message handler
- Handle cleanup in response to quit messages
Use Wire for compile-time dependency injection:
1. **File Organization**
- `wire_gen.go`: Auto-generated wire code
- `providers.go`: Define all Wire providers
- `interfaces.go`: Define interfaces for dependencies
2. **Injection Patterns**
- Prefer constructor injection over field injection
- Use interfaces for all external dependencies
- Keep constructors focused and simple
3. **Wire Provider Best Practices**
- Group related providers together
- Use Wire binding for interface implementations
- Document provider responsibilities
Use uber-go/zap for structured, high-performance logging:
1. **Log Levels**
- `debug`: Detailed development information
- `info`: General informational messages
- `warn`: Warning messages for potential issues
- `error`: Error conditions that need attention
2. **Context-Based Tracking**
- Include request IDs in logs for request tracking
- Use context to propagate request-scoped data
- Add relevant fields to all log entries
3. **Test Utilities**
- Use `testutil.NewTestLogger` for test logging
- Use `testutil.ReadLogFile` to read log output
- Use `testutil.VerifyLogContent` to verify log messages
4. **Linting Rules**
- Do NOT use `fmt` package for output in dashboard code
- Use logger package instead for all output
- Exception: Test files and main.go can use `fmt`
Build terminal UIs using Bubbletea (Model-View-Update pattern) and Lipgloss (styling):
1. **Widget System Features**
- Horizontal and vertical layout support
- Focus-based styling and navigation
- Minimum size constraints
- Dynamic resizing on terminal size changes
- Widget content caching for performance
2. **Base Widget Responsibilities**
- Dimension management (width, height, min size)
- Focus state management (focused/unfocused)
- Style selection based on state
- Default command handling (Cmd return values)
3. **Size Management**
- Define minimum size constraints
- Implement dynamic resize handling
- Manage content flow within constraints
- Cache computed sizes
4. **Focus Handling**
- Track focus state per widget
- Show focus indicators (borders, colors)
- Support keyboard navigation between widgets
Follow SOLID principles and composition patterns:
1. **Design Principles**
- **SRP** (Single Responsibility): Each component has one clear purpose
- **DRY** (Don't Repeat Yourself): Extract common patterns
- **ISP** (Interface Segregation): Small, focused interfaces
2. **Interface Segmentation**
- `Widget`: Core interface (Init/Update/View methods)
- `Focusable`: Focus management (Focus/Blur/IsFocused methods)
- `Sizable`: Size management (SetSize/GetDimensions methods)
3. **Composition Over Inheritance**
- Embed base widget for common functionality
- Compose widgets from smaller, reusable components
- Use interface composition for capabilities
Optimize for terminal UI performance:
1. **Performance Targets**
- View rendering: < 1ms per frame
- Memory allocations: < 1KB per operation
- CPU usage: < 5% during idle
2. **Optimization Techniques**
- Cache computed styles (avoid recalculating)
- Cache rendered content when unchanged
- Implement partial updates (only changed regions)
- Cache size calculations
3. **Benchmarking**
- Benchmark view rendering performance
- Benchmark update message handling
- Track memory allocations per operation
- Profile style operations
Comprehensive testing strategy across multiple levels:
1. **Unit Tests** (> 80% coverage for core logic)
- Widget behavior and state transitions
- Message handling and Cmd returns
- Style application and focus state
- Size calculations and constraints
2. **Integration Tests** (> 60% coverage)
- Widget interactions and communication
- Focus management across multiple widgets
- Layout behavior under different sizes
- Event propagation through component tree
3. **Benchmark Tests**
- View rendering performance
- Update message processing speed
- Memory allocation patterns
- Style computation overhead
4. **Test Utilities**
- `testutil.NewTestLogger`: Create test logger instance
- `testutil.NewUITest`: Set up UI testing environment
- `testutil.ReadLogFile`: Read log file contents
- **DO NOT** use local `setupTestLogger` functions; use testutil
Document all code comprehensively:
1. **Required Documentation**
- Document all exported symbols with godoc
- Provide package-level documentation
- Include usage examples in godoc
- Keep line length under 100 characters
2. **Widget Development Documentation**
- Document interface requirements clearly
- Explain size management approach
- Describe focus handling behavior
- Show common update patterns with examples
Handle errors gracefully without panicking:
1. **Error Handling Rules**
- Always return errors, never panic
- Wrap errors with context using `fmt.Errorf("%w", err)`
- Log errors with relevant context fields
- Provide user feedback for errors
2. **Edge Case Handling**
- Validate all inputs at boundaries
- Check for nil pointers before dereferencing
- Handle zero values appropriately
3. **Size Validation**
- Validate minimum dimensions before rendering
- Protect against overflow in size calculations
- Handle terminal resize edge cases
Structure the project with clear separation:
1. **Directory Structure**
- `/cmd`: Application entry points
- `/internal`: Private application code
- `/pkg`: Public library code
- `/docs`: Documentation files
- `/test`: Additional test files and utilities
- `/scripts`: Build and utility scripts
- `/configs`: Configuration files
2. **Widget File Structure**
- `components/widget.go`: Core widget interface definition
- `widgets/{type}/widget.go`: Widget implementation
- `styles/{widget}.go`: Widget-specific styles
- `widgets/{type}/widget_test.go`: Widget tests
Stay current with library updates:
1. **API Updates**
- Use latest APIs from Bubbletea and dependencies
- Update code when deprecation notices appear
- Document any temporary use of deprecated APIs
2. **Example Migrations**
- Use `p.Run()` instead of deprecated `p.Start()`
- Follow Bubbletea migration guides for breaking changes
Custom linting rules for this project:
1. **Depguard Rules**
- Deny list: `fmt` package (except in tests, main.go, logger package)
- Use logger package for all dashboard output
- Ignored files: `*_test.go`, `cmd/dashboard/main.go`, `internal/logger/*.go`
2. **Test Logger Rule**
- ERROR: Do not use local `setupTestLogger` functions
- Use `testutil.NewTestLogger` instead
- Applies to all `*_test.go` files
3. **Widget Interface Rule**
- ERROR: All widgets must implement full Widget interface
- Applies to all files in `**/widgets/**/*.go`
- Ensure Init, Update, and View methods are present
When creating a new widget:
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/go-dashboard-with-bubbletea/raw