GraphQL Apollo Client Rules

tl;dr: pull react-graphql-apollo-client-cursorrules-prompt-file.mdc from awesome-cursorrules before wiring Apollo Client into a Cursor project. Models default to fetch for GraphQL and skip the cache entirely.

What it does

This rule set configures Cursor to use Apollo Client the way it was designed: provider at the root, queries/mutations/fragments in dedicated folders, custom hooks per operation, and TypeScript-generated types for every operation. Without it, models reach for fetch, lose the normalized cache, and duplicate request logic.

Sourced from PatrickJS/awesome-cursorrules — the community registry for .mdc Project Rules.

The rules

// React + GraphQL (Apollo Client) .cursorrules

// Prefer functional components with hooks

const preferFunctionalComponents = true;

// GraphQL and Apollo Client best practices

const graphqlBestPractices = [
  "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",
];

// Folder structure

const folderStructure = `
src/
  components/
  graphql/
    queries/
    mutations/
    fragments/
  hooks/
  pages/
  utils/
`;

// Additional instructions

const additionalInstructions = `
1. Use Apollo Provider at the root of your app
2. Implement custom hooks for Apollo operations
3. Use TypeScript for type safety with GraphQL operations
4. Utilize Apollo Client's caching capabilities
5. Implement proper error boundaries for GraphQL errors
6. Use Apollo Client DevTools for debugging
7. Follow naming conventions for queries, mutations, and fragments
`;

Installation

Drop the .mdc into .cursor/rules/ of your project:

mkdir -p .cursor/rules
curl -sL \
  https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/react-graphql-apollo-client-cursorrules-prompt-file.mdc \
  -o .cursor/rules/react-graphql-apollo-client.mdc

Cursor picks up files in .cursor/rules/ automatically.

Setup snippet

// main.tsx
import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client'

const client = new ApolloClient({
  uri: 'https://api.example.com/graphql',
  cache: new InMemoryCache(),
  defaultOptions: {
    watchQuery: { fetchPolicy: 'cache-and-network' },
  },
})

function App() {
  return (
    <ApolloProvider client={client}>
      <YourApp />
    </ApolloProvider>
  )
}

Custom hook per operation

// hooks/useUser.ts
import { gql, useQuery } from '@apollo/client'

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

export function useUser(id: string) {
  const { data, loading, error } = useQuery(GET_USER, { variables: { id } })
  return { user: data?.user, loading, error }
}

Why it helps

Without Apollo-aware rules, models will:

• Use fetch for GraphQL and skip the normalized cache
• Inline query strings inside components instead of a graphql/ folder
• Skip fragments, so the same field selections get duplicated across queries
• Skip custom hooks, leaking useQuery calls deep into the component tree
• Forget the root <ApolloProvider>, so hooks throw at runtime

These rules keep Apollo Client as a single data layer instead of a half-wired dependency.

Gotchas

• These are Cursor .mdc rules, not a Claude Code CLAUDE.md file. For Claude Code, paraphrase into your project’s CLAUDE.md.
• Apollo Client v3+ uses gql from @apollo/client, not the standalone graphql-tag.
• Generated types via @graphql-codegen/cli pair with these rules. Cursor won’t auto-generate types without a codegen step.

Related

• TanStack Query v5 Rules — server-state alternative when you don’t need GraphQL’s normalized cache
• React Router v7 Rules — loaders can call Apollo client.query(...) for SSR prefetching