ARCHITECTURE.md
This document provides a comprehensive overview of Ratatui's architecture and crate organization, introduced in version 0.30.0.
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.
The Ratatui project is now organized as a Cargo workspace containing the following crates:
ratatui (Main Crate)WidgetRef and StatefulWidgetRef traitsratatui-coreWidget and StatefulWidget traitsText, Line, Span)ratatui-widgetsBlock, Paragraph, List, Chart, etc.ratatui-crosstermcrossterm crateratatui-termiontermion crateratatui-termwiztermwiz crateratatui-macrosratatui
├── ratatui-core
├── ratatui-widgets → ratatui-core
├── ratatui-crossterm → ratatui-core
├── ratatui-termion → ratatui-core
├── ratatui-termwiz → ratatui-core
└── ratatui-macros
ratatui-core for widget traits and typesratatui-core for backend traits and typesThe modular architecture provides different levels of API stability:
The split architecture enables:
ratatui-core without frequent updatesratatui crate with everything includedratatui-core for lightweight applicationsMost applications should continue using the main ratatui crate with minimal changes:
// No changes needed - everything is re-exported
use ratatui::{
widgets::{Block, Paragraph},
layout::{Layout, Constraint},
Terminal,
};
Consider migrating to ratatui-core for better stability:
// 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,
};
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.
Currently, all crates are versioned together for simplicity. Future versions may adopt independent versioning once the API stabilizes further.
This architecture was developed through extensive discussion and implementation across multiple PRs:
When contributing to the Ratatui project, please consider:
ratatui-core for fundamental improvementsratatui-widgets for widget-specific improvementsratatui crateSee the CONTRIBUTING.md guide for more details on the contribution process.