gpui-entity▌

Overview

An Entity<T> is a handle to state of type T, providing safe access and updates.

Key Methods:

• entity.read(cx) → &T - Read-only access
• entity.read_with(cx, |state, cx| ...) → R - Read with closure
• entity.update(cx, |state, cx| ...) → R - Mutable update
• entity.downgrade() → WeakEntity<T> - Create weak reference
• entity.entity_id() → EntityId - Unique identifier

Entity Types:

• Entity<T>: Strong reference (increases ref count)
• WeakEntity<T>: Weak reference (doesn't prevent cleanup, returns Result)

Quick Start

Creating and Using Entities

// Create entity
let counter = cx.new(|cx| Counter { count: 0 });

// Read state
let count = counter.read(cx).count;

// Update state
counter.update(cx, |state, cx| {
    state.count += 1;
    cx.notify(); // Trigger re-render
});

// Weak reference (for closures/callbacks)
let weak = counter.downgrade();
let _ = weak.update(cx, |state, cx| {
    state.count += 1;
    cx.notify();
});

In Components

struct MyComponent {
    shared_state: Entity<SharedData>,
}

impl MyComponent {
    fn new(cx: &mut App) -> Entity<Self> {
        let shared = cx.new(|_| SharedData::default());

        cx.new(|cx| Self {
            shared_state: shared,
        })
    }

    fn update_shared(&mut self, cx: &mut Context<Self>) {
        self.shared_state.update(cx, |state, cx| {
            state.value = 42;
            cx.notify();
        });
    }
}

Async Operations

impl MyComponent {
    fn fetch_data(&mut self, cx: &mut Context<Self>) {
        let weak_self = cx.entity().downgrade();

        cx.spawn(async move |cx| {
            let data = fetch_from_api().await;

            // Update entity safely
            let _ = weak_self.update(cx, |state, cx| {
                state.data = Some(data);
                cx.notify();
            });
        }).detach();
    }
}

Core Principles

Always Use Weak References in Closures

// ✅ Good: Weak reference prevents retain cycles
let weak = cx.entity().downgrade();
callback(move || {
    let _ = weak.update(cx, |state, cx| cx.notify());
});

// ❌ Bad: Strong reference may cause memory leak
let strong = cx.entity();
callback(move || {
    strong.update(cx, |state, cx| cx.notify());
});

Use Inner Context

// ✅ Good: Use inner cx from closure
entity.update(cx, |state, inner_cx| {
    inner_cx.notify(); // Correct
});

// ❌ Bad: Use outer cx (multiple borrow error)
entity.update(cx, |state, inner_cx| {
    cx.notify(); // Wrong!
});

Avoid Nested Updates

// ✅ Good: Sequential updates
entity1.update(cx, |state, cx| { /* ... */ });
entity2.update(cx, |state, cx| { /* ... */ });

// ❌ Bad: Nested updates (may panic)
entity1.update(cx, |_, cx| {
    entity2.update(cx, |_, cx| { /* ... */ });
});

Common Use Cases

1. Component State: Internal state that needs reactivity
2. Shared State: State shared between multiple components
3. Parent-Child: Coordinating between related components (use weak refs)
4. Async State: Managing state that changes from async operations
5. Observations: Reacting to changes in other entities

Reference Documentation

Complete API Documentation

• Entity API: See api-reference.md
  • Entity types, methods, lifecycle
  • Context methods, async operations
  • Error handling, type conversions

Implementation Guides

• Patterns: See

  how to use gpui-entity
  CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity

  How to use gpui-entity on Cursor

  AI-first code editor with Composer

  1

  Prerequisites

  Before installing skills in Cursor, ensure your development environment meets these requirements:

  • ›Cursor installed and configured on your development machine
  • ›Node.js version 16.0+ with npm package manager (verify with node --version)
  • ›Active project directory or workspace where you want to add gpui-entity

  2

  Execute installation command

  Execute the skills CLI command in your project's root directory to begin installation:

  $npx skills add https://github.com/longbridge/gpui-component --skill gpui-entitycopy

  The skills CLI fetches gpui-entity from GitHub repository longbridge/gpui-component and configures it for Cursor.

  3

  Select Cursor when prompted

  The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:

  ◆ Which agents do you want to install to?

  │

  │ ── Universal (.agents/skills) ── always included ────

  │ • Amp

  │ • Antigravity

  │ • Cline

  │ • Codex

  │ ●Cursor(selected)

  │ • Cursor

  │ • Windsurf

  4

  Verify installation

  Confirm successful installation by checking the skill directory location:

  .cursor/skills/gpui-entity

  Reload or restart Cursor to activate gpui-entity. Access the skill through slash commands (e.g., /gpui-entity) or your agent's skill management interface.

  ⚠

  Security & Verification Notice

  We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.

  Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.

  Additional Resources

  ›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?