mirror of
https://github.com/ratatui/ratatui.git
synced 2025-09-27 04:50:46 +00:00
5620e06b1a
Adds summary-level crate organization documentation to all crates explaining the modular workspace structure and when to use each crate. Links to ARCHITECTURE.md for detailed information.
204 lines
6.7 KiB
Markdown
204 lines
6.7 KiB
Markdown
# Ratatui Architecture
|
|
|
|
This document provides a comprehensive overview of Ratatui's architecture and crate
|
|
organization, introduced in version 0.30.0.
|
|
|
|
## Overview
|
|
|
|
Starting with Ratatui 0.30.0, the project was reorganized from a single monolithic crate into
|
|
a modular workspace consisting of multiple specialized crates. This architectural decision was
|
|
made to improve modularity, reduce compilation times, enable more flexible dependency
|
|
management, and provide better API stability for third-party widget libraries.
|
|
|
|
## Crate Organization
|
|
|
|
The Ratatui project is now organized as a Cargo workspace containing the following crates:
|
|
|
|
### Core Crates
|
|
|
|
#### `ratatui` (Main Crate)
|
|
|
|
- **Purpose**: The main entry point that most applications should use
|
|
- **Contents**: Re-exports everything from other crates for convenience, plus experimental features
|
|
- **Target Users**: Application developers building terminal UIs
|
|
- **Key Features**:
|
|
- Complete widget ecosystem
|
|
- Backend implementations
|
|
- Layout system
|
|
- Terminal management
|
|
- Experimental `WidgetRef` and `StatefulWidgetRef` traits
|
|
|
|
#### `ratatui-core`
|
|
|
|
- **Purpose**: Foundational types and traits for the Ratatui ecosystem
|
|
- **Contents**: Core widget traits, text types, buffer, layout, style, and symbols
|
|
- **Target Users**: Widget library authors, minimalist projects
|
|
- **Key Features**:
|
|
- `Widget` and `StatefulWidget` traits
|
|
- Text rendering (`Text`, `Line`, `Span`)
|
|
- Buffer management
|
|
- Layout system
|
|
- Style and color definitions
|
|
- Symbol collections
|
|
|
|
#### `ratatui-widgets`
|
|
|
|
- **Purpose**: Built-in widget implementations
|
|
- **Contents**: All standard widgets like `Block`, `Paragraph`, `List`, `Chart`, etc.
|
|
- **Target Users**: Applications needing standard widgets, widget library authors
|
|
- **Key Features**:
|
|
- Complete set of built-in widgets
|
|
- Optimized implementations
|
|
- Comprehensive documentation and examples
|
|
|
|
### Backend Crates
|
|
|
|
#### `ratatui-crossterm`
|
|
|
|
- **Purpose**: Crossterm backend implementation
|
|
- **Contents**: Cross-platform terminal backend using the `crossterm` crate
|
|
- **Target Users**: Applications targeting multiple platforms
|
|
|
|
#### `ratatui-termion`
|
|
|
|
- **Purpose**: Termion backend implementation
|
|
- **Contents**: Unix-specific terminal backend using the `termion` crate
|
|
- **Target Users**: Unix-specific applications requiring low-level control
|
|
|
|
#### `ratatui-termwiz`
|
|
|
|
- **Purpose**: Termwiz backend implementation
|
|
- **Contents**: Terminal backend using the `termwiz` crate
|
|
- **Target Users**: Applications needing advanced terminal features
|
|
|
|
### Utility Crates
|
|
|
|
#### `ratatui-macros`
|
|
|
|
- **Purpose**: Declarative macros for common patterns and boilerplate reduction
|
|
- **Contents**: Macros for common patterns and boilerplate reduction
|
|
- **Target Users**: Applications and libraries wanting macro support
|
|
|
|
## Dependency Relationships
|
|
|
|
```text
|
|
ratatui
|
|
├── ratatui-core
|
|
├── ratatui-widgets → ratatui-core
|
|
├── ratatui-crossterm → ratatui-core
|
|
├── ratatui-termion → ratatui-core
|
|
├── ratatui-termwiz → ratatui-core
|
|
└── ratatui-macros
|
|
```
|
|
|
|
### Key Dependencies
|
|
|
|
- **ratatui-core**: Foundation for all other crates
|
|
- **ratatui-widgets**: Depends on `ratatui-core` for widget traits and types
|
|
- **Backend crates**: Each depends on `ratatui-core` for backend traits and types
|
|
- **ratatui**: Depends on all other crates and re-exports their public APIs
|
|
|
|
## Design Principles
|
|
|
|
### Stability and Compatibility
|
|
|
|
The modular architecture provides different levels of API stability:
|
|
|
|
- **ratatui-core**: Designed for maximum stability to minimize breaking changes for widget
|
|
libraries
|
|
- **ratatui-widgets**: Focused on widget implementations with moderate stability requirements
|
|
- **Backend crates**: Isolated from core changes, allowing backend-specific updates
|
|
- **ratatui**: Main crate that can evolve more freely while maintaining backward compatibility
|
|
through re-exports
|
|
|
|
### Compilation Performance
|
|
|
|
The split architecture enables:
|
|
|
|
- **Reduced compilation times**: Widget libraries only need to compile core types
|
|
- **Parallel compilation**: Different crates can be compiled in parallel
|
|
- **Selective compilation**: Applications can exclude unused backends or widgets
|
|
|
|
### Ecosystem Benefits
|
|
|
|
- **Widget Library Authors**: Can depend on stable `ratatui-core` without frequent updates
|
|
- **Application Developers**: Can use the convenient `ratatui` crate with everything included
|
|
- **Minimalist Projects**: Can use only `ratatui-core` for lightweight applications
|
|
|
|
## Migration Guide
|
|
|
|
### For Application Developers
|
|
|
|
Most applications should continue using the main `ratatui` crate with minimal changes:
|
|
|
|
```rust
|
|
// No changes needed - everything is re-exported
|
|
use ratatui::{
|
|
widgets::{Block, Paragraph},
|
|
layout::{Layout, Constraint},
|
|
Terminal,
|
|
};
|
|
```
|
|
|
|
### For Widget Library Authors
|
|
|
|
Consider migrating to `ratatui-core` for better stability:
|
|
|
|
```rust
|
|
// Before (0.29.x and earlier)
|
|
use ratatui::{
|
|
widgets::{Widget, StatefulWidget},
|
|
buffer::Buffer,
|
|
layout::Rect,
|
|
};
|
|
|
|
// After (0.30.0+)
|
|
use ratatui_core::{
|
|
widgets::{Widget, StatefulWidget},
|
|
buffer::Buffer,
|
|
layout::Rect,
|
|
};
|
|
```
|
|
|
|
### Backwards Compatibility
|
|
|
|
All existing code using the `ratatui` crate will continue to work unchanged, as the main crate
|
|
re-exports all public APIs from the specialized crates.
|
|
|
|
## Future Considerations
|
|
|
|
### Potential Enhancements
|
|
|
|
- **Widget-specific crates**: Further split widgets into individual crates for even more
|
|
granular dependencies
|
|
- **Plugin system**: Enable dynamic widget loading and third-party widget ecosystems
|
|
- **Feature flags**: More granular feature flags for compile-time customization
|
|
|
|
### Version Synchronization
|
|
|
|
Currently, all crates are versioned together for simplicity. Future versions may adopt
|
|
independent versioning once the API stabilizes further.
|
|
|
|
## Related Issues and PRs
|
|
|
|
This architecture was developed through extensive discussion and implementation across multiple
|
|
PRs:
|
|
|
|
- [Issue #1388](https://github.com/ratatui/ratatui/issues/1388): Original RFC for modularization
|
|
- [PR #1459](https://github.com/ratatui/ratatui/pull/1459): Move ratatui crate into workspace
|
|
folder
|
|
- [PR #1460](https://github.com/ratatui/ratatui/pull/1460): Move core types to ratatui-core
|
|
- [PR #1474](https://github.com/ratatui/ratatui/pull/1474): Move widgets into ratatui-widgets
|
|
crate
|
|
|
|
## Contributing
|
|
|
|
When contributing to the Ratatui project, please consider:
|
|
|
|
- **Core changes**: Submit PRs against `ratatui-core` for fundamental improvements
|
|
- **Widget changes**: Submit PRs against `ratatui-widgets` for widget-specific improvements
|
|
- **Backend changes**: Submit PRs against the appropriate backend crate
|
|
- **Integration changes**: Submit PRs against the main `ratatui` crate
|
|
|
|
See the [CONTRIBUTING.md](CONTRIBUTING.md) guide for more details on the contribution process.
|