Skip to main content

Welcome to Query Cache Flow

Query Cache Flow is a pattern and framework for managing TanStack Query cache keys in React applications. It provides a structured approach to eliminate manual cache key management and ensures automatic, type-safe cache invalidation.

The Problem​

When building React applications with TanStack Query, developers face several challenges:

  1. Manual cache keys are error-prone - String-based keys lead to typos and inconsistencies
  2. Cache invalidation is hard - Knowing which queries to invalidate after mutations is complex
  3. Generated hooks need wrapping - KUBB-generated hooks lack cache key infrastructure
  4. No standardization - Every team invents their own patterns

The Query Cache Flow Solution​

Query Cache Flow eliminates these problems through a simple philosophy:

REST → OpenAPI → KUBB → Autogenerated wrappers → Zero-thought usage

With Query Cache Flow, developers never think about cache keys. The framework handles:

  • Consistent cache key structure across your application
  • Automatic cascade invalidation for mutations
  • Type-safe cache operations with full TypeScript support
  • Optimistic updates with built-in normalize functions
  • Seamless integration with KUBB-generated hooks

Quick Example​

import { createQueryGroupCRUD } from 'src/queries';

// Create a complete CRUD query group
const accountsQueryGroup = createQueryGroupCRUD<string>('accounts');

// Wrap KUBB-generated hook with proper cache key
export const useAccounts = () =>
  generatedUseAccounts({
    query: { queryKey: [accountsQueryGroup.list.queryKey] },
  });

// Mutations automatically invalidate related queries
await createAccount.mutateAsync(data);
invalidateQueriesForKeys([accountsQueryGroup.create.invalidates]);

That's it. No thinking about cache keys. No manual invalidation logic. Just build features.

What Makes Query Cache Flow Different?​

Query Cache Flow is not a package you install. It's a pattern you copy into your project and adapt to your needs. The implementation is simple, transparent, and yours to modify.

  • ~170 lines of code - Easy to understand and customize
  • Zero dependencies - Only requires TanStack Query
  • Type-safe - Full TypeScript support with generics
  • Battle-tested - Used in production React applications
  • Framework-agnostic - Works with any REST API pattern

Ready to Get Started?​

  1. Installation - Copy the implementation into your project
  2. Quick Start - Build your first query group
  3. Core Concepts - Understand the architecture

Or jump straight to practical patterns to see real-world examples.