# gpui-query

Zero-boilerplate async state management for GPUI. Brings TanStack Query patterns to Rust and the Zed editor's GPUI framework with caching, retry, cooperative cancellation, and persistence.

Every page is also available as `.md` and `.txt` — append either extension to any URL above for a token-light copy of that page.

## Documentation

- [Introduction](https://gpui-query.freeoxide.com/docs/): gpui-query is async state management for GPUI, the Rust framework behind Zed. Declarative queries with caching, retries, and cancellation built in.
- [Queries](https://gpui-query.freeoxide.com/docs/api/queries): use_query API reference for gpui-query: query keys, fetchers, cache and request policies, status handling, and reactive updates in GPUI components.
- [Installation](https://gpui-query.freeoxide.com/docs/getting-started/installation): Install gpui-query in a Rust GPUI app: add the crate, register the global QueryClient, and verify your setup with a first query.
- [Caching](https://gpui-query.freeoxide.com/docs/guides/caching): Configure caching in gpui-query: how NoCache, Ttl, and StaleWhileRevalidate policies decide when data is fresh, stale, or refetched in the background.
- [Devtools](https://gpui-query.freeoxide.com/docs/advanced/devtools): Inspect live query and mutation state in gpui-query: ClientDiagnostic snapshots and patterns for building a debug panel.
- [Observers](https://gpui-query.freeoxide.com/docs/advanced/observers): Reactive subscriptions with status deduplication for queries, infinite queries, and mutations
- [Mutations](https://gpui-query.freeoxide.com/docs/api/mutations): use_mutation API reference for gpui-query: dispatching writes from GPUI components, success and error callbacks, and coordinating cache invalidation.
- [Quick Start](https://gpui-query.freeoxide.com/docs/getting-started/quick-start): Write your first gpui-query query and mutation in a GPUI app: fetch data with use_query, render each status, and dispatch a write with use_mutation.
- [Error handling](https://gpui-query.freeoxide.com/docs/guides/error-handling): Handle query errors in gpui-query: the error status lifecycle, retries with backoff, cooperative cancellation, and rendering failures in GPUI views.
- [gpui-query vs. raw async](https://gpui-query.freeoxide.com/docs/advanced/comparison): What you stop writing when you move from cx.spawn and manual caching to gpui-query
- [Infinite Queries](https://gpui-query.freeoxide.com/docs/api/infinite-queries): use_infinite_query API reference for gpui-query: bidirectional page fetching, max_pages limits, and rendering paginated data in GPUI components.
- [Retry](https://gpui-query.freeoxide.com/docs/guides/retry): Configure automatic retries in gpui-query: fixed and exponential backoff RetryPolicy options, caps, and how retries interact with cancellation.
- [API Reference](https://gpui-query.freeoxide.com/docs/advanced/api-reference): A flat index of the public types, hooks, and functions gpui-query exports
- [QueryClient](https://gpui-query.freeoxide.com/docs/api/query-client): QueryClient API reference for gpui-query: the global registry that owns query resources, garbage collection, invalidation, and cache persistence.
- [Persistence](https://gpui-query.freeoxide.com/docs/guides/persistence): Save and restore cached query data across app restarts with the async Persister trait, persist_with, and hydrate.
- [Migrating from v1 to v2](https://gpui-query.freeoxide.com/docs/advanced/migration): The breaking and behavioral changes from gpui-query v1 to the options-first v2 API
- [HTTP cache headers](https://gpui-query.freeoxide.com/docs/guides/http-caching): Turn a server's Cache-Control into a gpui-query CachePolicy (server wins) and persist ETags for cheap 304 refetches with gpui-query-http.
- [Query Keys](https://gpui-query.freeoxide.com/docs/guides/query-keys): Hierarchical, cheap-to-clone cache keys and the QueryKeyFilter for bulk operations
- [The Select Pattern](https://gpui-query.freeoxide.com/docs/guides/select-pattern): Derive multiple views from one cached query with SelectTransform and use_query_select
- [Claude Code skills](https://gpui-query.freeoxide.com/docs/guides/claude-skills): Install gpui-query's Claude Code skills so your AI assistant writes correct hooks, caching, retry, and persistence code without guessing the API.

## Links

- [GitHub](https://github.com/freeoxide/gpui-query): Source code and issues
- [Introduction](https://gpui-query.freeoxide.com/docs/): What is gpui-query and why you need it
- [Blog](https://gpui-query.freeoxide.com/blog)
- [Changelog](https://gpui-query.freeoxide.com/changelog)
- [FAQ](https://gpui-query.freeoxide.com/faq)