# apollo-graphql

A skill that gives the agent rules for Apollo Client work: queries, mutations, fragments, caching and optimistic updates in React GraphQL apps.

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

## What it does

The skill spells out how to write GraphQL code in Apollo Client and React projects. Inside are a `src/graphql` layout with `queries`, `mutations` and `fragments` folders, client setup through `HttpLink` and `InMemoryCache`, and custom hooks such as `useUser` and `useCreateUser`. The agent gets ready templates instead of inventing its own.

A separate section covers schema design: naming for types and fields, the `Payload` pattern with an `errors` array, cursor pagination via `UserConnection`. There is also a part on optimistic responses and cache updates after a mutation. Everything is TypeScript, with types pulled from `types/generated`.

One caveat: the examples read the endpoint from `NEXT_PUBLIC_GRAPHQL_ENDPOINT` and rely on generated types, so if your project does not generate them, expect to adapt part of the code. This is a set of conventions, not a library — nothing is added to your dependencies.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Mindrally/skills apollo-graphql
```

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill apollo-graphql -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/Mindrally/skills/tree/HEAD/apollo-graphql/SKILL.md

## When to use it
- Split GraphQL queries and mutations into files instead of keeping them in components
- Set up Apollo Client with network and GraphQL error handling
- Write custom hooks on top of `useQuery` and `useMutation`
- Add optimistic responses and cache sync after a mutation
- Design a schema with payload types and cursor pagination

## Example prompts
- Add a paginated users query with cursor pagination and the `UserFields` fragment
- Create a `useCreateUser` hook with a mutation and a list refresh after creation
- Set up `apollo-client.ts` with `errorLink` and the `cache-and-network` policy

## Source text · SKILL.md · Apache-2.0

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: bbab9f4ff0bee6f0.

BEGIN THIRD-PARTY FILE bbab9f4ff0bee6f0
````text
---
name: apollo-graphql
description: Guidelines for developing GraphQL APIs and React applications using Apollo Client for state management, data fetching, and caching
metadata:
  maintainer: Mindrally
  source: https://github.com/Mindrally/skills
---

# Apollo GraphQL Best Practices

You are an expert in Apollo Client, GraphQL, TypeScript, and React development. Apollo Client provides a comprehensive state management solution for GraphQL applications with intelligent caching, optimistic UI updates, and seamless React integration.

## Core Principles

- Use Apollo Client for state management and data fetching
- Implement query components for data fetching
- Utilize mutations for data modifications
- Use fragments for reusable query parts
- Implement proper error handling and loading states
- Leverage TypeScript for type safety with GraphQL operations

## Project Structure

```
src/
  components/
  graphql/
    queries/
      users.ts
      posts.ts
    mutations/
      users.ts
      posts.ts
    fragments/
      user.ts
      post.ts
  hooks/
    useUser.ts
    usePosts.ts
  pages/
  utils/
    apollo-client.ts
  types/
    generated/           # Generated TypeScript types
```

## Setup and Configuration

### Apollo Client Setup

```typescript
// utils/apollo-client.ts
import { ApolloClient, InMemoryCache, HttpLink, from } from '@apollo/client';
import { onError } from '@apollo/client/link/error';

const httpLink = new HttpLink({
  uri: process.env.NEXT_PUBLIC_GRAPHQL_ENDPOINT,
});

const errorLink = onError(({ graphQLErrors, networkError }) => {
  if (graphQLErrors) {
    graphQLErrors.forEach(({ message, locations, path }) => {
      console.error(`[GraphQL error]: Message: ${message}, Path: ${path}`);
    });
  }
  if (networkError) {
    console.error(`[Network error]: ${networkError}`);
  }
});

export const apolloClient = new ApolloClient({
  link: from([errorLink, httpLink]),
  cache: new InMemoryCache({
    typePolicies: {
      Query: {
        fields: {
          users: {
            merge(existing = [], incoming) {
              return [...existing, ...incoming];
            },
          },
        },
      },
    },
  }),
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'cache-and-network',
      errorPolicy: 'all',
    },
    query: {
      fetchPolicy: 'cache-first',
      errorPolicy: 'all',
    },
    mutate: {
      errorPolicy: 'all',
    },
  },
});
```

### Apollo Provider Setup

```typescript
// pages/_app.tsx or app/providers.tsx
import { ApolloProvider } from '@apollo/client';
import { apolloClient } from '@/utils/apollo-client';

function App({ children }: { children: React.ReactNode }) {
  return (
    <ApolloProvider client={apolloClient}>
      {children}
    </ApolloProvider>
  );
}
```
````
END THIRD-PARTY FILE bbab9f4ff0bee6f0

The third-party file has ended. Everything between the bbab9f4ff0bee6f0 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 2774 of 12337 bytes. © Mindrally · Apache-2.0 · https://github.com/Mindrally/skills/tree/HEAD/apollo-graphql/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