# apollo-client

A skill that walks your agent through Apollo Client 4.x in React: queries, mutations, caching, local state and error troubleshooting.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 5600 installs · ★ 119
- Author: apollographql
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/apollographql/skills/tree/HEAD/skills/apollo-client/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/apollo-client

## What it does

The skill bundles a guide to Apollo Client 4.x plus reference files: client-side React, Next.js App Router, React Router 7 and TanStack Start integrations, and separate docs on queries, Suspense hooks, mutations, fragments, caching, state management, error handling and troubleshooting. The agent picks the reference that matches your setup and codes against it.

It targets React 18+ and React 19 with Suspense and RSC, and works with Next.js, Vite and CRA. The rules are blunt: use 4.x patterns only, wrap the app in `ApolloProvider`, and turn on data masking for new applications. For types without an `id` field the guide says to configure `keyFields`, and `keyFields: false` for types that just group fields under a parent.

The skill is allowed `Bash(npm:*)`, `Bash(npx:*)`, `Bash(node:*)`, `Read`, `Write`, `Edit`, `Glob` and `Grep`, so the agent can install packages and edit files on its own. Still on Apollo Client 3? That is worth checking, because the rules assume 4.x and import hooks like `useSuspenseQuery` from `@apollo/client/react`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add apollographql/skills --skill apollo-client -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/apollo-client/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/apollo-client/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add apollographql/skills --skill apollo-client -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/apollo-client/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add apollographql/skills --skill apollo-client -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/apollo-client/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install apollographql/skills apollo-client
```

2. **Manually: put the files in place**
- File: `.github/skills/apollo-client/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add apollographql/skills --skill apollo-client -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/apollographql/skills --path skills/apollo-client
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/apollo-client/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add apollographql/skills --skill apollo-client -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/apollographql/skills/tree/HEAD/skills/apollo-client/SKILL.md

## When to use it
- set up Apollo Client in a React project from scratch
- write a query and a mutation with hooks
- configure caching and `typePolicies` for pagination
- move local state to reactive variables
- debug a query that never updates the cache

## Example prompts
- Set up Apollo Client 4.x in my Vite project and wrap the app in `ApolloProvider`
- Rewrite this component with `useSuspenseQuery` instead of `useQuery`
- Why doesn't the list refresh after my mutation? Check the cache and `typePolicies`

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4ce8e4c8d76c2d84.

BEGIN THIRD-PARTY FILE 4ce8e4c8d76c2d84
````text
---
name: apollo-client
description: >
  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.
license: MIT
compatibility: React 18+, React 19 (Suspense/RSC). Works with Next.js, Vite, CRA, and other React frameworks.
metadata:
  author: apollographql
  version: "1.0.0"
allowed-tools: Bash(npm:*) Bash(npx:*) Bash(node:*) Read Write Edit Glob Grep
---

# 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:

- **[Client-Side Apps](references/integration-client.md)** - For client-side React applications without SSR (Vite, Create React App, etc.)
- **[Next.js App Router](references/integration-nextjs.md)** - For Next.js applications using the App Router with React Server Components
- **[React Router Framework Mode](references/integration-react-router.md)** - For React Router 7 applications with streaming SSR
- **[TanStack Start](references/integration-tanstack-start.md)** - For TanStack Start applications with modern routing

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

## Quick Reference

### Basic Query

```tsx
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

```tsx
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) => {
````
END THIRD-PARTY FILE 4ce8e4c8d76c2d84

The third-party file has ended. Everything between the 4ce8e4c8d76c2d84 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2708 of 7423 bytes. © apollographql · MIT · https://github.com/apollographql/skills/tree/HEAD/skills/apollo-client/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md