ReddRadar
Agent skill
gpui-global
Global state management in GPUI. Use when implementing global state, app-wide configuration, or shared resources.
Install this agent skill to your Project
npx add-skill https://github.com/longbridge/gpui-component/tree/main/.claude/skills/gpui-global
SKILL.md
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
use gpui::Global;
#[derive(Clone)]
struct AppSettings {
theme: Theme,
language: String,
}
impl Global for AppSettings {}
Set and Access Globals
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::<AppSettings>();
println!("Theme: {:?}", settings.theme);
});
}
Update Globals
impl MyComponent {
fn change_theme(&mut self, new_theme: Theme, cx: &mut Context<Self>) {
cx.update_global::<AppSettings, _>(|settings, cx| {
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
#[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::<AppConfig>();
2. Feature Flags
#[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<impl IntoElement> {
let flags = cx.global::<FeatureFlags>();
if flags.enable_beta_features {
Some(div().child("Beta feature"))
} else {
None
}
}
}
3. Shared Services
#[derive(Clone)]
struct ServiceRegistry {
http_client: Arc<HttpClient>,
logger: Arc<Logger>,
}
impl Global for ServiceRegistry {}
impl MyComponent {
fn fetch_data(&mut self, cx: &mut Context<Self>) {
let registry = cx.global::<ServiceRegistry>();
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
#[derive(Clone)]
struct GlobalState {
database: Arc<Database>, // Cheap to clone
cache: Arc<RwLock<Cache>>,
}
impl Global for GlobalState {}
✅ Immutable by Default
Globals are read-only by default. Use interior mutability when needed:
#[derive(Clone)]
struct Counter {
count: Arc<AtomicUsize>,
}
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
// ❌ 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
- Global trait, set_global, update_global
- Interior mutability patterns
- Best practices and anti-patterns
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
longbridge/gpui-component
gpui-test
Writing tests for GPUI applications. Use when testing components, async operations, or UI behavior.
longbridge/gpui-component
gpui-async
Async operations and background tasks in GPUI. Use when working with async, spawn, background tasks, or concurrent operations. Essential for handling async I/O, long-running computations, and coordinating between foreground UI updates and background work.
longbridge/gpui-component
gpui-action
Action definitions and keyboard shortcuts in GPUI. Use when implementing actions, keyboard shortcuts, or key bindings.
longbridge/gpui-component
github-pull-request-description
Write a description to description GitHub Pull Request.
longbridge/gpui-component
gpui-layout-and-style
Layout and styling in GPUI. Use when styling components, layout systems, or CSS-like properties.
longbridge/gpui-component
gpui-context
Context management in GPUI including App, Window, and AsyncApp. Use when working with contexts, entity updates, or window operations. Different context types provide different capabilities for UI rendering, entity management, and async operations.
Didn't find tool you were looking for?