Introduction
Caching GraphQL responses on Flutter apps is essential for performance, offline UX, and reduced network usage in mobile development. Two common caching patterns are document (or response) caching and normalized (entity) caching. This article contrasts both approaches, explains trade-offs, and shows practical implementation ideas you can adapt to any GraphQL client in Flutter.
Understanding Cache Types
Document cache stores each response blob keyed by operation (query/mutation) and variables. Reads are cheap: you return the stored JSON for that operation. Writes are atomic: save the entire response. Document cache is simple to implement and reason about, and it’s a good fit when responses are mostly read-only or ephemeral.
Normalized cache breaks responses into entities and stores them by unique identifiers (usually typename + id). When the same entity appears across queries, the cache keeps a single canonical copy and reconstructs queries by composing those entities. This enables fine-grained updates and consistent UI updates when one entity changes.
Normalized Cache: Benefits And Trade-Offs
Benefits:
Strong consistency: Updating one entity updates all queries that reference it without re-fetching the entire query.
Small writes: Only modified entities are written back to the store.
Optimistic updates and partial writes are more precise because you target entities.
Trade-offs:
Complexity: You need stable unique IDs and a normalization strategy (key fields or custom ID generators).
Rehydration complexity: Reconstructing a query result requires assembling entities and lists, which is more code than returning a stored JSON document.
Storage overhead: Indexes and references add bookkeeping.
When to choose normalized cache in Flutter mobile development:
Your app frequently displays the same entities in multiple screens (lists, detail pages).
You rely heavily on optimistic UI and local updates.
You want minimal network churn when a small entity changes.
Document Cache: Benefits And Trade-Offs
Benefits:
Simplicity: Store/return the raw JSON mapped to a query key. Easy to debug and implement.
Predictable invalidation: Invalidate a specific operation when needed (e.g., after mutation).
Lower bookkeeping: No need to generate or maintain entity keys.
Trade-offs:
Harder to keep data consistent across queries that share entities — you must manually invalidate multiple documents or re-fetch.
Larger writes: Any change often requires writing whole query responses back into cache.
When document cache works best:
Read-heavy screens where data shape is stable and not shared across many views.
Small apps where simplicity and quick iteration trump fine-grained consistency.
Choosing And Implementing A Strategy
Hybrid strategies combine both patterns: use a normalized store for frequently-shared entities and a document cache for heavy, rarely-shared query blobs. Invalidation policies are crucial: for normalized caches, clear or update affected entities; for document caches, track which queries depend on which entities so you can expire them after a mutation.
Practical tips for Flutter:
If you control the backend, ensure entities expose stable IDs and typename metadata — that makes normalization reliable.
Adopt a single source of truth for IDs (e.g., server-side id field) so the same entity is recognized across different queries.
Instrument your cache with small tools to visualize entity usage and document hits to guide optimization.
Example: Simple conceptual normalized store (toy example, not library-specific):
class NormalizedStore {
final Map<String, Map<String, dynamic>> entities = {};
void writeEntity(String typename, String id, Map<String, dynamic> data) {
entities.putIfAbsent(typename, () => {})[id] = data;
}
Map<String, dynamic>? readEntity(String typename, String id) => entities[typename]?[id];
}Example: Document cache storing full responses keyed by operation name and variables:
class DocumentCache {
final Map<String, Map<String, dynamic>> store = {};
String _key(String operation, Map<String, dynamic>? vars) => '$operation:${vars ?? {}}';
void write(String operation, Map<String, dynamic>? vars, Map<String, dynamic> data) => store[_key(operation, vars)] = data;
Map<String, dynamic>? read(String operation, Map<String, dynamic>? vars) => store[_key(operation, vars)];
}Integration with clients: popular Flutter GraphQL clients allow you to plug stores. If you need normalized behavior, configure the client with ID resolvers and type policies. For document caching, use an in-memory or persistent blob store keyed by query signature.
Vibe Studio
Vibe Studio, powered by Steve’s advanced AI agents, is a revolutionary no-code, conversational platform that empowers users to quickly and efficiently create full-stack Flutter applications integrated seamlessly with Firebase backend services. Ideal for solo founders, startups, and agile engineering teams, Vibe Studio allows users to visually manage and deploy Flutter apps, greatly accelerating the development process. The intuitive conversational interface simplifies complex development tasks, making app creation accessible even for non-coders.
Conclusion
Normalized and document caches serve different needs in Flutter mobile development. Normalized caches excel when entities are shared and updated frequently; document caches excel when simplicity and predictable invalidation matter. Hybrid approaches often offer the best practical trade-offs: normalize core entities and keep bulky, infrequently-shared responses as documents. Choose a strategy based on your app’s sharing patterns, write/update frequency, and complexity tolerance, and instrument your cache to validate assumptions in production.
