gpui-global
🎯Skillfrom longbridge/gpui-component
|Manages global application state and configuration in GPUI, enabling centralized data access and sharing across components.
Installation
npx skills add https://github.com/longbridge/gpui-component --skill gpui-globalSkill Details
Global state management in GPUI. Use when implementing global state, app-wide configuration, or shared resources.
Overview
Global state in GPUI provides app-wide shared data accessible from any context.
Key Trait: Global - Implement on types to make them globally accessible
Quick Start
Define Global State
```rust
use gpui::Global;
#[derive(Clone)]
struct AppSettings {
theme: Theme,
language: String,
}
impl Global for AppSettings {}
```
Set and Access Globals
```rust
fn main() {
let app = Application::new();
app.run(|cx: &mut App| {
// Set global
cx.set_global(AppSettings {
theme: Theme::Dark,
language: "en".to_string(),
});
// Access global (read-only)
let settings = cx.global::
println!("Theme: {:?}", settings.theme);
});
}
```
Update Globals
```rust
impl MyComponent {
fn change_theme(&mut self, new_theme: Theme, cx: &mut Context
cx.update_global::
settings.theme = new_theme;
// Global updates don't trigger automatic notifications
// Manually notify components that care
});
cx.notify(); // Re-render this component
}
}
```
Common Use Cases
1. App Configuration
```rust
#[derive(Clone)]
struct AppConfig {
api_endpoint: String,
max_retries: u32,
timeout: Duration,
}
impl Global for AppConfig {}
// Set once at startup
cx.set_global(AppConfig {
api_endpoint: "https://api.example.com".to_string(),
max_retries: 3,
timeout: Duration::from_secs(30),
});
// Access anywhere
let config = cx.global::
```
2. Feature Flags
```rust
#[derive(Clone)]
struct FeatureFlags {
enable_beta_features: bool,
enable_analytics: bool,
}
impl Global for FeatureFlags {}
impl MyComponent {
fn render_beta_feature(&self, cx: &App) -> Option
let flags = cx.global::
if flags.enable_beta_features {
Some(div().child("Beta feature"))
} else {
None
}
}
}
```
3. Shared Services
```rust
#[derive(Clone)]
struct ServiceRegistry {
http_client: Arc
logger: Arc
}
impl Global for ServiceRegistry {}
impl MyComponent {
fn fetch_data(&mut self, cx: &mut Context
let registry = cx.global::
let client = registry.http_client.clone();
cx.spawn(async move |cx| {
let data = client.get("api/data").await?;
// Process data...
Ok::<_, anyhow::Error>(())
}).detach();
}
}
```
Best Practices
✅ Use Arc for Shared Resources
```rust
#[derive(Clone)]
struct GlobalState {
database: Arc
cache: Arc
}
impl Global for GlobalState {}
```
✅ Immutable by Default
Globals are read-only by default. Use interior mutability when needed:
```rust
#[derive(Clone)]
struct Counter {
count: Arc
}
impl Global for Counter {}
impl Counter {
fn increment(&self) {
self.count.fetch_add(1, Ordering::SeqCst);
}
fn get(&self) -> usize {
self.count.load(Ordering::SeqCst)
}
}
```
❌ Don't: Overuse Globals
```rust
// ❌ Bad: Too many globals
cx.set_global(UserState { ... });
cx.set_global(CartState { ... });
cx.set_global(CheckoutState { ... });
// ✅ Good: Use entities for component state
let user_entity = cx.new(|_| UserState { ... });
```
When to Use
Use Globals for:
- App-wide configuration
- Feature flags
- Shared services (HTTP client, logger)
- Read-only reference data
Use Entities for:
- Component-specific state
- State that changes frequently
- State that needs notifications
Reference Documentation
- API Reference: See [api-reference.md](references/api-reference.md)
- Global trait, set_global, update_global
- Interior mutability patterns
- Best practices and anti-patterns
More from this repository10
Enforces consistent GPUI component design patterns by providing a comprehensive style guide for creating and reviewing Rust UI components.
Enables asynchronous operations and background tasks in GPUI, allowing seamless coordination between UI updates and concurrent computations.
Enables type-safe event handling, subscriptions, and observations for coordinating component interactions in GPUI applications.
Provides CSS-like layout and styling for Rust GPUI components using type-safe, chainable methods for flexbox, sizing, colors, and spacing.
Manages application state through safe, concurrent entities with read, update, and weak reference capabilities for reactive and async-friendly state handling in GPUI.
Enables keyboard-driven focus management and navigation between focusable elements in GPUI user interfaces.
Defines and manages keyboard-driven actions and key bindings for declarative UI interactions in GPUI applications.
gpui-context skill from longbridge/gpui-component
Enables comprehensive testing of GPUI applications with deterministic, single-threaded test execution for UI components and async operations.
Enables low-level, performance-critical custom UI element creation with precise control over layout, painting, and interaction phases in GPUI.