Apollo Client Inspector

A debugging tool for Apollo Client that helps identify and diagnose cache misses in GraphQL operations, inspect cache contents, and monitor request/response cycles.

Features

• 🔍 Detects and logs detailed information about GraphQL query cache misses
• 📊 Shows exactly which fields are missing from the cache
• 🎛️ Configurable logging and debug mode activation
• 🔄 Tracks both requests and responses

Installation

npm install apollo-client-inspector
# or
yarn add apollo-client-inspector

Usage

import { ApolloClient, InMemoryCache } from '@apollo/client';
import { createApolloInspector } from 'apollo-client-inspector';

// Create the cache
const cache = new InMemoryCache();

// Create the inspector link
const inspectorLink = createApolloInspector(cache, 
  {
    onCacheFulfilled: (operation) =>
      console.debug(
        { variables: operation.variables },
        `[ApolloClient] cache fulfilled for query: ${operation.operationName}`
      ),
    onCacheMiss: (operation, missing) =>
      console.debug(
        { missing, variables: operation.variables },
        `[ApolloClient] cache miss for query: ${operation.operationName}`
      ),
    onRequest: (operation) =>
      console.debug(
        { variables: operation.variables },
        `[ApolloClient] Making request for ${operation.type} ${operation.operationName}`
      ),
    onResponse: (operation, response) =>
      console.debug(
        { variables: operation.variables, response },
        `[ApolloClient] Response received for ${operation.type} ${operation.operationName}`
      ),

  }
);

// Add it to your Apollo Client setup
const client = new ApolloClient({
  cache,
  link: ApolloLink.from([
    inspectorLink,
    // ... your other links
    httpLink,
  ]),
});

Context override

You can override the callback for individual operations by adding the callback to the query context:

useQuery(QUERY_GQL, { onCacheMiss: (operation, missing) => console.error('unexpected cache miss') })

Disabling the inspector

The inspector is enabled by default but you can selectively disable it in the options.

1. With the options object:

   createApolloInspector(cache, logger, { enabled: true });

2. With a function:

   createApolloInspector(cache, logger, { 
     enabled: () => process.env.NODE_ENV === 'development'
   });

Sample Output

When a cache miss occurs, you'll see log messages like:

[ApolloInspector] Cache miss for query: GetUserProfile: ["user.address.zipCode", "user.recentOrders"]

This tells you:

• Which operation had a cache miss (GetUserProfile)
• Exactly which fields were missing from the cache (user.address.zipCode and user.recentOrders)

Type Definitions

export interface ApolloClientInspectorCallbacks {
  onCacheFulfilled?: (operation: Operation) => void;
  onCacheMiss?: (operation: Operation, missing: MissingFieldError[]) => void;
  onRequest?: (operation: Operation & { type: OperationTypeNode }) => void;
  onResponse?: (operation: Operation & { type: OperationTypeNode }, response: any) => void;
}

// defined in graphql package, as are Operation and MissingFieldError
export type OperationTypeNode = 'query' | 'mutation' | 'subscription';

export interface ApolloInspectorOptions {
  disable?: boolean | (() => boolean);
}

Why Use Apollo Client Inspector?

• Better Debugging: Quickly identify why your components are re-rendering due to network requests
• Performance Tuning: Find opportunities to optimize your GraphQL operations
• Learning Tool: Understand how Apollo Client's cache works in practice
• Environment Flexibility: Works in any JavaScript environment (browsers, Node.js, React Native)

License

MIT