apollo-caching-strategies

name	apollo-caching-strategies
description	Use when implementing Apollo caching strategies including cache policies, optimistic UI, cache updates, and normalization.
allowed-tools	["Read","Write","Edit","Grep","Glob","Bash"]

Apollo Caching Strategies

Master Apollo Client's caching mechanisms for building performant applications with optimal data fetching and state management strategies.

Overview

Apollo Client's intelligent cache is a normalized, in-memory data store that allows for efficient data fetching and updates. Understanding cache policies and management strategies is crucial for building high-performance apps.

Installation and Setup

Cache Configuration

// apollo/cache.js
import { InMemoryCache, makeVar } from '@apollo/client';

export const cache = new InMemoryCache({
  typePolicies: {
    Query: {
      fields: {
        posts: {
          // Pagination with offset
          keyArgs: ['filter'],
          merge(existing = [], incoming, { args }) {
            const merged = existing.slice(0);
            const offset = args?.offset || 0;

            for (let i = 0; i < incoming.length; i++) {
              merged[offset + i] = incoming[i];
            }

            return merged;
          }
        }
      }
    },
    Post: {
      keyFields: ['id'],
      fields: {
        comments: {
          merge(existing = [], incoming) {
            return [...existing, ...incoming];
          }
        }
      }
    },
    User: {
      keyFields: ['email'],
      fields: {
        fullName: {
          read(_, { readField }) {
            return `${readField('firstName')} ${readField('lastName')}`;
          }
        }
      }
    }
  }
});

Core Patterns

1. Fetch Policies

// Different fetch policies for different use cases
import { useQuery } from '@apollo/client';
import { GET_POSTS } from './queries';

// cache-first (default): Check cache first, network if not found
function CacheFirstPosts() {
  const { data } = useQuery(GET_POSTS, {
    fetchPolicy: 'cache-first'
  });
  return <PostsList posts={data?.posts} />;
}

// cache-only: Never make network request, cache or error
function CacheOnlyPosts() {
  const { data } = useQuery(GET_POSTS, {
    fetchPolicy: 'cache-only'
  });
  return <PostsList posts={data?.posts} />;
}

// cache-and-network: Return cache immediately, update with network
function CacheAndNetworkPosts() {
  const { data, loading, networkStatus } = useQuery(GET_POSTS, {
    fetchPolicy: 'cache-and-network',
    notifyOnNetworkStatusChange: true
  });

   (
    
  );
}


 () {
   { data } = (, {
    : 
  });
   ;
}


 () {
   { data } = (, {
    : 
  });
   ;
}


 () {
   { data, refetch } = (, {
    : 
  });

   (
    
  );
}

2. Cache Reads and Writes

// apollo/cacheOperations.js
import { gql } from '@apollo/client';

// Read from cache
export function readPostFromCache(client, postId) {
  try {
    const data = client.readQuery({
      query: gql`
        query GetPost($id: ID!) {
          post(id: $id) {
            id
            title
            body
          }
        }
      `,
      variables: { id: postId }
    });
    return data?.post;
  } catch (error) {
    console.error('Post not in cache:', error);
    return null;
  }
}

// Write to cache
export function writePostToCache(client, post) {
  client.writeQuery({
    query: gql`
      query GetPost($id: ID!) {
        post( ) 
          id
          title
          body
        
      
    `,
    : { : post. },
    : { post }
  });
}


  () {
   client.({
    : ,
    : gql`
  });
}


  () {
  client.({
    : ,
    : gql`,
    : {
      likesCount
    }
  });
}


  () {
  client..({
    : client..({ : , : postId }),
    : {
      () {
         currentCount + ;
      },
      () {
         ;
      }
    }
  });
}

3. Optimistic Updates

// components/OptimisticLike.js
import { useMutation } from '@apollo/client';
import { LIKE_POST } from '../mutations';

function OptimisticLike({ post }) {
  const [likePost] = useMutation(LIKE_POST, {
    variables: { postId: post.id },

    // Optimistic response
    optimisticResponse: {
      __typename: 'Mutation',
      likePost: {
        __typename: 'Post',
        id: post.id,
        likesCount: post.likesCount + 1,
        isLiked: true
      }
    },

    // Update cache
    update(cache, { data: { likePost } }) {
      cache.modify({
        id: cache.identify(post),
        fields: {
          likesCount() {
            return likePost.likesCount;
          },
          isLiked() {
            return likePost.isLiked;
          }
        }
      });
    },

    // Handle errors
    onError() {
      .(, error);
      
    }
  });

   (
    
  );
}


 () {
   [createComment] = (, {
    :  ({
      : ,
      : {
        : ,
        : ,
        body,
        :  ().(),
        : {
          : ,
          : currentUser.,
          : currentUser.,
          : currentUser.
        }
      }
    }),

    () {
      
      cache.({
        : cache.({ : , : postId }),
        : {
          () {
             newCommentRef = cache.({
              : createComment,
              : gql`
            });
             [...existing, newCommentRef];
          },
          () {
             count + ;
          }
        }
      });
    }
  });

   ;
}

4. Cache Eviction

// apollo/eviction.js
export function evictPost(client, postId) {
  // Evict specific post
  client.cache.evict({
    id: client.cache.identify({ __typename: 'Post', id: postId })
  });

  // Garbage collect
  client.cache.gc();
}

export function evictField(client, postId, fieldName) {
  // Evict specific field
  client.cache.evict({
    id: client.cache.identify({ __typename: 'Post', id: postId }),
    fieldName
  });
}

export function evictAllPosts(client) {
  // Evict all posts from cache
  client.cache.modify({
    fields: {
      posts(existing, { DELETE }) {
        return DELETE;
      }
    }
  });

  client.cache.gc();
}

// Usage in delete mutation
function DeletePost({ postId }) {
  const [deletePost] = (, {
    : { : postId },

    () {
      
      cache.({
        : {
          () {
             existingPosts.(
               postId !== (, ref)
            );
          }
        }
      });

      
      cache.({ : cache.({ : , : postId }) });
      cache.();
    }
  });

   ;
}

5. Reactive Variables

// apollo/reactiveVars.js
import { makeVar, useReactiveVar } from '@apollo/client';

// Create reactive variables
export const cartItemsVar = makeVar([]);
export const themeVar = makeVar('light');
export const isModalOpenVar = makeVar(false);
export const notificationsVar = makeVar([]);

// Helper functions
export function addToCart(item) {
  const cart = cartItemsVar();
  cartItemsVar([...cart, item]);
}

export function removeFromCart(itemId) {
  const cart = cartItemsVar();
  cartItemsVar(cart.filter(item => item.id !== itemId));
}

export function clearCart() {
  cartItemsVar([]);
}

export function toggleTheme() {
  const current = themeVar();
  themeVar(current ===  ?  : );
}

  () {
   notifications = ();
  ([...notifications, {
    : .(),
    ...notification
  }]);
}


 () {
   cartItems = (cartItemsVar);

   (
    
  );
}


 cache =  ({
  : {
    : {
      : {
        : {
          () {
             ();
          }
        },
        : {
          () {
             ();
          }
        }
      }
    }
  }
});

6. Pagination Strategies

// Offset-based pagination
const POSTS_QUERY = gql`
  query GetPosts($limit: Int!, $offset: Int!) {
    posts(limit: $limit, offset: $offset) {
      id
      title
      body
    }
  }
`;

function OffsetPagination() {
  const { data, fetchMore } = useQuery(POSTS_QUERY, {
    variables: { limit: 10, offset: 0 }
  });

  return (
    <div>
      <PostsList posts={data?.posts} />
      <button
        onClick={() =>
          fetchMore({
            variables: { offset: data.posts.length }
          })
        }
      >
        Load More
      </button>
    </div>
  );
}

// Cursor-based pagination
const CURSOR_POSTS_QUERY = gql`
  query GetPosts: Int, : String 
    posts ,  ) 
      edges 
        cursor
        node 
          id
          title
          body
        
      
      pageInfo 
        hasNextPage
        endCursor
      
    
  
`;

 () {
   { data, fetchMore } = (, {
    : { :  }
  });

   (
    
  );
}


 cache =  ({
  : {
    : {
      : {
        : {
          : [],
          () {
             (!existing)  incoming;

             { offset =  } = args;
             merged = existing.();

             ( i = ; i < incoming.; i++) {
              merged[offset + i] = incoming[i];
            }

             merged;
          }
        }
      }
    }
  }
});


 { offsetLimitPagination }  ;

 cache =  ({
  : {
    : {
      : {
        : ()
      }
    }
  }
});

7. Cache Persistence

// apollo/persistedCache.js
import { InMemoryCache } from '@apollo/client';
import { persistCache, LocalStorageWrapper } from 'apollo3-cache-persist';

export async function createPersistedCache() {
  const cache = new InMemoryCache({
    typePolicies: {
      // Your type policies
    }
  });

  await persistCache({
    cache,
    storage: new LocalStorageWrapper(window.localStorage),
    maxSize: 1048576, // 1 MB
    debug: true,
    trigger: 'write', // or 'background'
  });

  return cache;
}

// Usage in client setup
import { ApolloClient } from '@apollo/client';

async function initApollo() {
  const cache = await createPersistedCache();

  const client = new ApolloClient({
    uri: ,
    cache
  });

   client;
}


  () {
  client.(); 
  .(); 
}


 cache =  ({
  : {
    : {
      : {
        
        : {
          () {
             ;
          }
        }
      }
    }
  }
});

8. Cache Warming

// apollo/cacheWarming.js
import { gql } from '@apollo/client';

export async function warmCache(client) {
  // Preload critical queries
  await Promise.all([
    client.query({
      query: gql`
        query GetCurrentUser {
          me {
            id
            name
            email
          }
        }
      `
    }),

    client.query({
      query: gql`
        query GetRecentPosts {
          posts(limit: 20) {
            id
            title
            excerpt
          }
        }
      `
    })
  ]);
}

// Prefetch on hover
function PostLink({ postId }) {
  const client = useApolloClient();

  const prefetch = () => {
    client.query({
      query: GET_POST,
      variables: { id: postId }
    });
  };

  return (
    
  );
}

9. Cache Redirects

// apollo/cache.js
const cache = new InMemoryCache({
  typePolicies: {
    Query: {
      fields: {
        post: {
          read(_, { args, toReference }) {
            // Redirect to cached object
            return toReference({
              __typename: 'Post',
              id: args.id
            });
          }
        }
      }
    },

    User: {
      fields: {
        // Computed field from cache
        fullName: {
          read(_, { readField }) {
            const firstName = readField('firstName');
            const lastName = readField('lastName');
            return `${firstName} ${lastName}`;
          }
        },

        // Field with arguments
        posts: {
          read(existing, { args, readField }) {
            if (args?.published !== undefined) {
              return existing?.filter(ref =>
                readField('published', ref) === args.published
              );
            }
             existing;
          }
        }
      }
    }
  }
});

10. Cache Monitoring and Debugging

// apollo/monitoring.js
export function logCacheContents(client) {
  const cache = client.extract();
  console.log('Cache contents:', cache);
}

export function watchCacheChanges(client) {
  const observer = client.cache.watch({
    query: gql`
      query GetAllData {
        posts {
          id
          title
        }
      }
    `,
    callback: (data) => {
      console.log('Cache changed:', data);
    }
  });

  return observer;
}

// Development helpers
if (process.env.NODE_ENV === 'development') {
  window.apolloClient = client;
  window.logCache = () => logCacheContents(client);

  // Cache size monitoring
  setInterval(() => {
    const cacheSize = JSON.stringify(client.extract()).;
    .();
  }, );
}


 {  }  ;
 {  }  ;

 () {
   (
    
  );
}


 () {
   client = ();
   [cacheData, setCacheData] = ({});

  ( {
     data = client.();
    (data);
  }, [client]);

   (
    
  );
}

Best Practices

1. Choose appropriate fetch policies - Match policy to data freshness needs
2. Use optimistic updates - Improve perceived performance
3. Normalize cache properly - Configure keyFields correctly
4. Implement pagination - Handle large datasets efficiently
5. Persist critical data - Cache auth state and user preferences
6. Monitor cache size - Prevent memory bloat
7. Use reactive variables - Manage local state efficiently
8. Warm cache strategically - Prefetch critical data
9. Evict unused data - Clean up after deletions
10. Debug cache issues - Use Apollo DevTools effectively

Common Pitfalls

1. Wrong fetch policy - Using cache-first for real-time data
2. Cache denormalization - Missing or incorrect keyFields
3. Memory leaks - Not evicting deleted items
4. Over-caching - Caching too much data
5. Stale data - Not invalidating cache properly
6. Missing updates - Forgetting to update cache after mutations
7. Incorrect merges - Wrong pagination merge logic
8. Cache thrashing - Too many cache writes
9. Persistence issues - Storing sensitive data
10. No error handling - Not handling cache read failures

When to Use

• Building data-intensive applications
• Implementing offline-first features
• Creating real-time collaborative apps
• Developing mobile applications
• Building e-commerce platforms
• Creating social media applications
• Implementing complex state management
• Developing admin dashboards
• Building content management systems
• Creating analytics applications

Resources

• Apollo Cache Documentation
• Advanced Cache Patterns
• Cache Persistence
• Apollo DevTools
• Optimistic UI Guide