Index of every page on this site: llms.txt
All skills
apollographql avatar

/apollo-client

@0ff461c
Run it yourself

Guide for building React applications with Apollo Client 4.x. Use this skill when: (1) setting up Apollo Client in a React project, (2) writing GraphQL queries or mutations with hooks, (3) configuring caching or cache policies, (4) managing local state with reactive variables, (5) troubleshooting Apollo Client errors or performance issues.

Use this Skill: https://skilld.dev/gh/apollographql/apollo-client/apollo-client

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈89 tokens for metadata: the name and description. ≈1.7k when used: this file. ≈38k more on demand in 13 files.

Description uses 4.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈357 characters, or 4.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Apollo Client 4.x Guide

Apollo Client is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. Version 4.x brings improved caching, better TypeScript support, and React 19 compatibility.

Integration Guides

Choose the integration guide that matches your application setup:

Each guide includes installation steps, configuration, and framework-specific patterns optimized for that environment.

Quick Reference

Basic Query

import { gql } from "@apollo/client";
import { useQuery } from "@apollo/client/react";

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
    }
  }
`;

function UserProfile({ userId }: { userId: string }) {
  const { loading, error, data, dataState } = useQuery(GET_USER, {
    variables: { id: userId },
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  // TypeScript note: for stricter type narrowing, you can also check `dataState === "complete"` before accessing data
  return <div>{data?.user.name}</div>;
}

Basic Mutation

import { gql } from "@apollo/client";
import { useMutation } from "@apollo/client/react";

const CREATE_USER = gql`
  mutation CreateUser($input: CreateUserInput!) {
    createUser(input: $input) {
      id
      name
    }
  }
`;

function CreateUserForm() {
  const [createUser, { loading, error }] = useMutation(CREATE_USER);

  const handleSubmit = async (name: string) => {
    await createUser({ variables: { input: { name } } });
  };

  return <button onClick={() => handleSubmit("John")}>Create User</button>;
}

Suspense Query

import { Suspense } from "react";
import { useSuspenseQuery } from "@apollo/client/react";

function UserProfile({ userId }: { userId: string }) {
  const { data } = useSuspenseQuery(GET_USER, {
    variables: { id: userId },
  });

  return <div>{data.user.name}</div>;
}

function App() {
  return (
    <Suspense fallback={<p>Loading user...</p>}>
      <UserProfile userId="1" />
    </Suspense>
  );
}

Reference Files

Detailed documentation for specific topics:

Key Rules

Query Best Practices

  • Each page should generally only have one query, composed from colocated fragments. Use useFragment or useSuspenseFragment in all non-page-components. Use @defer to allow slow fields below the fold to stream in later and avoid blocking the page load.
  • Fragments are for colocation, not reuse. Each fragment should describe exactly the data needs of a specific component, not be shared across components for common fields. See Fragments reference for details on fragment colocation and data masking.
  • Always handle loading and error states in UI when using non-suspenseful hooks (useQuery, useLazyQuery). When using Suspense hooks (useSuspenseQuery, useBackgroundQuery), React handles this through <Suspense> boundaries and error boundaries.
  • Use fetchPolicy to control cache behavior per query
  • Use the TypeScript type server to look up documentation for functions and options (Apollo Client has extensive docblocks)

Mutation Best Practices

  • If the schema permits, mutation return values should return everything necessary to update the cache. Neither manual updates nor refetching should be necessary.
  • If the mutation response is insufficient, carefully weigh manual cache manipulation vs refetching. Manual updates risk missing server logic. Consider optimistic updates with a granular refetch if needed.
  • Handle errors gracefully in the UI
  • Use refetchQueries sparingly (prefer letting the cache update automatically)

Caching Best Practices

  • Configure keyFields for types without id field
  • Disable normalization by setting keyFields: false for types that don't include an identifier and are meant to group related fields under the parent
  • Use typePolicies for pagination and computed fields
  • Understand cache normalization to debug issues
  • Enable data masking for all new applications - it prevents components from accessing fragment data they don't own, enforcing proper data boundaries and preventing over-rendering

Performance

  • Avoid over-fetching with proper field selection
  • Configure appropriate fetchPolicy per use case
  • Use @defer for incremental delivery of deferred query parts, and @stream for streaming list fields (@stream available in Apollo Client 4.1+)
  • Prefer Suspense hooks (useSuspenseQuery, useBackgroundQuery) in modern applications for better loading state handling and code simplicity

Ground Rules

  • ALWAYS use Apollo Client 4.x patterns (not v3 or earlier)
  • ALWAYS wrap your app with ApolloProvider
  • ALWAYS handle loading and error states when using non-suspenseful hooks
  • PREFER Suspense hooks (useSuspenseQuery, useBackgroundQuery) in modern applications for better DX
  • NEVER store Apollo Client in React state (use module-level or context)
  • PREFER cache-first for read-heavy data, network-only for real-time data
  • USE TypeScript for better type safety with GraphQL
  • IMPLEMENT proper cache updates instead of refetching entire queries
  • ADVISE the human steering you to look into Apollo DevTools when collaboratively debugging Apollo Client issues

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides comprehensive documentation and integration guides for Apollo Client 4.x. It follows security best practices, such as recommending the use of HttpOnly cookies for authentication and providing clear guidance on error handling and performance optimization. No malicious patterns or security vulnerabilities were detected.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at 0ff461c. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 7 months ago
What it can do
Runs commands
metadata
{
  "author": "apollographql",
  "version": "1.0.0"
}
All 1 allowed tools
Bash(npm:*) Bash(npx:*) Bash(node:*) Read Write Edit Glob Grep
Other metadata
compatibility
React 18+, React 19 (Suspense/RSC). Works with Next.js, Vite, CRA, and other React frameworks.

README badge

README badge for apollographql/apollo-client