\n {data?.posts.map((post) =>
\n );\n}\n```\n\n## Cache Manipulation\n\n### cache.readQuery\n\n```typescript\n// Read data from cache\nconst data = cache.readQuery({\n query: GET_TODOS,\n});\n\n// With variables\nconst userData = cache.readQuery({\n query: GET_USER,\n variables: { id: \"1\" },\n});\n```\n\n### cache.writeQuery\n\n```typescript\n// Write data to cache\ncache.writeQuery({\n query: GET_TODOS,\n data: {\n todos: [\n { __typename: \"Todo\", id: \"1\", text: \"Buy milk\", completed: false },\n ],\n },\n});\n\n// With variables\ncache.writeQuery({\n query: GET_USER,\n variables: { id: \"1\" },\n data: {\n user: { __typename: \"User\", id: \"1\", name: \"John\" },\n },\n});\n```\n\n### cache.readFragment / cache.writeFragment\n\n```typescript\n// Read a specific object - use cache.identify for safety\nconst user = cache.readFragment({\n id: cache.identify({ __typename: \"User\", id: \"1\" }),\n fragment: gql`\n fragment UserFragment on User {\n id\n name\n email\n }\n `,\n});\n\n// Apollo Client 4.1+: Use 'from' parameter (recommended)\nconst user = cache.readFragment({\n from: { __typename: \"User\", id: \"1\" },\n fragment: gql`\n fragment UserFragment on User {\n id\n name\n email\n }\n `,\n});\n\n// Update a specific object\ncache.writeFragment({\n id: cache.identify({ __typename: \"User\", id: \"1\" }),\n fragment: gql`\n fragment UpdateUser on User {\n name\n }\n `,\n data: {\n name: \"Jane\",\n },\n});\n\n// Apollo Client 4.1+: Use 'from' parameter (recommended)\ncache.writeFragment({\n from: { __typename: \"User\", id: \"1\" },\n fragment: gql`\n fragment UpdateUser on User {\n name\n }\n `,\n data: {\n name: \"Jane\",\n },\n});\n```\n\n### cache.modify\n\n```typescript\n// Modify fields directly\ncache.modify({\n id: cache.identify(user),\n fields: {\n // Set new value\n name: () => \"New Name\",\n\n // Transform existing value\n postCount: (existing) => existing + 1,\n\n // Delete field\n temporaryField: (_, { DELETE }) => DELETE,\n\n // Add to array\n friends: (existing, { toReference }) => [\n ...existing,\n toReference({ __typename: \"User\", id: \"2\" }),\n ],\n },\n});\n```\n\n### cache.evict\n\n```typescript\n// Remove object from cache\ncache.evict({ id: \"User:1\" });\n\n// Remove specific field\ncache.evict({ id: \"User:1\", fieldName: \"friends\" });\n\n// Remove with broadcast (trigger re-renders)\ncache.evict({ id: \"User:1\", broadcast: true });\n```\n\n## Garbage Collection\n\n### Manual Garbage Collection\n\n```typescript\n// After evicting objects, clean up dangling references\ncache.evict({ id: \"User:1\" });\ncache.gc();\n```\n\n### Retaining Objects\n\n```typescript\n// Prevent objects from being garbage collected\nconst release = cache.retain(\"User:1\");\n\n// Later, allow GC\nrelease();\ncache.gc();\n```\n\n### Inspecting Cache\n\n```typescript\n// Get all cached data\nconst cacheContents = cache.extract();\n\n// Restore cache state\ncache.restore(previousCacheContents);\n\n// Get identified object cache key\nconst userId = cache.identify({ __typename: \"User\", id: \"1\" });\n// Returns: 'User:1'\n```\n","docs/agent-skills/apollo-client/references/error-handling.md":"# Error Handling Reference (Apollo Client 4.x)\n\nNote that Apollo Client 4.x handles errors differently than Apollo Client 3.x.\nThis reference documents the updated error handling mechanisms, error types, and best practices for managing errors in your Apollo Client applications.\nFor older Apollo Client 3.x error handling documentation, see [Apollo Client 3.x Error Handling](https://www.apollographql.com/docs/react/v3/data/error-handling).\n\n## Table of Contents\n\n- [Understanding Errors](#understanding-errors)\n- [Error Types](#error-types)\n- [Identifying Error Types](#identifying-error-types)\n- [GraphQL Error Policies](#graphql-error-policies)\n- [Error Links](#error-links)\n- [Retry Link](#retry-link)\n- [Error Boundaries](#error-boundaries)\n\n## Understanding Errors\n\nErrors in Apollo Client fall into two main categories: **GraphQL errors** and **network errors**. Each category has specific error classes that provide detailed information about what went wrong.\n\n### GraphQL Errors\n\nGraphQL errors are related to server-side execution of a GraphQL operation:\n\n- **Syntax errors** (e.g., malformed query)\n- **Validation errors** (e.g., query includes a non-existent schema field)\n- **Resolver errors** (e.g., error while populating a query field)\n\nIf a syntax or validation error occurs, the server doesn't execute the operation. If resolver errors occur, the server can still return partial data.\n\nExample server response with GraphQL error:\n\n```json\n{\n \"errors\": [\n {\n \"message\": \"Cannot query field \\\"nonexistentField\\\" on type \\\"Query\\\".\",\n \"locations\": [{ \"line\": 2, \"column\": 3 }],\n \"extensions\": {\n \"code\": \"GRAPHQL_VALIDATION_FAILED\"\n }\n }\n ],\n \"data\": null\n}\n```\n\nIn Apollo Client 4.x, GraphQL errors are represented by the [`CombinedGraphQLErrors`](https://apollographql.com/docs/react/api/errors/CombinedGraphQLErrors) error type.\n\n### Network Errors\n\nNetwork errors occur when attempting to communicate with your GraphQL server:\n\n- `4xx` or `5xx` HTTP response status codes\n- Network unavailability\n- JSON parsing failures\n- Custom errors from Apollo Link request handlers\n\nNetwork errors might be represented by special error types, but if an api such as the `fetch` API throws a native error (e.g., `TypeError`), Apollo Client will pass it through as-is.\nThrown values that don't fulfill the standard `ErrorLike` interface are wrapped in the [`UnconventionalError`](https://apollographql.com/docs/react/api/errors/UnconventionalError) class, which fulfills the `ErrorLike` interface. As such, you can expect any error returned by Apollo Client to fulfill the `ErrorLike` interface.\n\n```ts\nexport interface ErrorLike {\n message: string;\n name: string;\n stack?: string;\n}\n```\n\n## Error Types\n\nApollo Client 4.x provides specific error classes for different error scenarios:\n\n### CombinedGraphQLErrors\n\nRepresents GraphQL errors returned by the server. Most common error type in applications.\n\n```tsx\nimport { CombinedGraphQLErrors } from \"@apollo/client/errors\";\n\nfunction UserProfile({ userId }: { userId: string }) {\n const { data, error } = useQuery(GET_USER, {\n variables: { id: userId },\n });\n\n // no need to check for nullishness of error, CombinedGraphQLErrors.is handles that\n if (CombinedGraphQLErrors.is(error)) {\n // Handle GraphQL errors\n return (\n \n {error.graphQLErrors.map((err, i) => (\n
\n );\n }\n\n return data ? GraphQL Error: {err.message}
\n ))}\n\n
\n );\n}\n```\n\n### Avoid setting a Global Error Policy\n\nWhile it is possible to set a global error policy using `defaultOptions`, in practice this is discouraged as it can lead to unexpected behavior and type safety issues. The return types of the TypeScript hooks may change depending on the `errorPolicy` passed into the hook, and this can conceptually not take global `defaultOptions` error policies into account. As such, it is best to set the `errorPolicy` per operation as needed.\n\n## Error Links\n\nThe `ErrorLink` can be used to e.g. log error globally or perform specific side effects based on errors happening.\n\nAn `ErrorLink` can't be used to swallow errors fully, but it can be used to retry an operation after handling an error, in which case the error wouldn't propagate. Otherwise, the most common use for `ErrorLink` is logging.\n\n```ts\nimport { ErrorLink } from \"@apollo/client/link/error\";\n\nconst errorLink = new ErrorLink(({ error, operation, forward }) => {\n if (someCondition(error)) {\n // Retry the request, returning the new observable\n return forward(operation);\n }\n\n // Log the error for any unhandled GraphQL errors or network errors.\n console.log(`[Error]: ${error.message}`);\n\n // If nothing is returned from the error handler callback, the error will be\n // emitted from the link chain as normal.\n});\n```\n\n### Retry Link\n\nAlternatively, you can use the `RetryLink` from `@apollo/client/link/retry` to implement retry logic for failed operations.\n\n```typescript\nimport { RetryLink } from \"@apollo/client/link/retry\";\n\nconst retryLink = new RetryLink({\n delay: {\n initial: 300,\n max: Infinity,\n jitter: true,\n },\n attempts: {\n max: 5,\n retryIf: (error, operation) => {\n // Retry on network errors\n return !!error && operation.operationName !== \"SensitiveOperation\";\n },\n },\n});\n\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n link: from([retryLink, errorLink, httpLink]),\n});\n```\n\n### Custom Retry Logic\n\n```typescript\nconst retryLink = new RetryLink({\n attempts: (count, operation, error) => {\n // Don't retry mutations\n if (\n operation.query.definitions.some(\n (def) =>\n def.kind === \"OperationDefinition\" && def.operation === \"mutation\"\n )\n ) {\n return false;\n }\n\n // Retry up to 3 times on network errors\n return count < 3 && !!error;\n },\n delay: (count) => {\n // Exponential backoff\n return Math.min(1000 * Math.pow(2, count), 30000);\n },\n});\n```\n\n## Error Boundaries\n\nWhen using suspenseful hooks, you should use React Error Boundaries for graceful error handling.\n\n### Non-suspense per-Component Error Handling\n\n```tsx\nimport {\n CombinedGraphQLErrors,\n ServerError,\n ServerParseError,\n} from \"@apollo/client/errors\";\n\nfunction SafeUserList() {\n const { data, error, loading, refetch } = useQuery(GET_USERS, {\n errorPolicy: \"all\",\n notifyOnNetworkStatusChange: true,\n });\n\n // Handle network errors\n if (ServerError.is(error) || ServerParseError.is(error)) {\n return (\n Good: {data?.goodField}
\n {error &&Bad: {error.message}}\n \n {CombinedGraphQLErrors.is(error) && (\n \n Some data may be incomplete: {error.graphQLErrors[0].message}\n \n )}\n\n {loading &&
\n );\n}\n```\n","docs/agent-skills/apollo-client/references/fragments.md":"# Fragments Reference\n\nGraphQL fragments define a set of fields for a specific type. In Apollo Client, fragments are especially powerful when colocated with components to define each component's data requirements independently, creating a clear separation of concerns and enabling better component composition.\n\n## Table of Contents\n\n- [What Are Fragments](#what-are-fragments)\n- [Basic Fragment Syntax](#basic-fragment-syntax)\n- [Fragment Colocation](#fragment-colocation)\n- [Fragment Reading Hooks](#fragment-reading-hooks)\n- [Data Masking](#data-masking)\n- [Fragment Registry](#fragment-registry)\n- [TypeScript Integration](#typescript-integration)\n- [Best Practices](#best-practices)\n\n## What Are Fragments\n\nA GraphQL fragment defines a set of fields for a specific GraphQL type. Fragments are defined on a specific GraphQL type and can be included in operations using the spread operator (`...`).\n\nIn Apollo Client, fragments serve a specific purpose:\n\n**Fragments are for colocation, not reuse.** Each component should declare its data needs in a dedicated fragment. This allows components to independently evolve their data requirements without creating artificial dependencies between unrelated parts of your application.\n\nFragments enable:\n\n1. **Component colocation**: Define the exact data requirements for a component alongside the component code\n2. **Independent evolution**: Change a component's data needs without affecting other components\n3. **Code organization**: Compose fragments together to build complete queries that mirror your component hierarchy\n\n## Basic Fragment Syntax\n\n### Defining a Fragment\n\n```typescript\nimport { gql } from \"@apollo/client\";\n\nconst USER_FRAGMENT = gql`\n fragment UserFields on User {\n id\n name\n email\n avatarUrl\n }\n`;\n```\n\nEvery fragment includes:\n\n- A unique name (`UserFields`)\n- The type it operates on (`User`)\n- The fields to select\n\n### Using Fragments in Queries\n\nInclude fragments in queries using the spread operator:\n\n```typescript\nconst GET_USER = gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n ...UserFields\n }\n }\n\n ${USER_FRAGMENT}\n`;\n```\n\nWhen using GraphQL Code Generator with the recommended configuration (typescript, typescript-operations, and typed-document-node plugins), fragments defined in your source files are automatically picked up and generated into typed document nodes. The generated fragment documents already include the fragment definition, so you don't need to interpolate them manually into queries.\n\n## Fragment Colocation\n\nFragment colocation is the practice of defining fragments in the same file as the component that uses them. This creates a clear contract between components and their data requirements.\n\n### Why Colocate Fragments\n\n- **Locality**: Data requirements live next to the code that uses them\n- **Maintainability**: Changes to component UI and data needs happen together\n- **Type safety**: TypeScript can infer exact types from colocated fragments\n- **Independence**: Components can evolve their data requirements without affecting other components\n\n### Colocation Pattern\n\nThe recommended pattern for colocating fragments with components:\n\n```tsx\nimport { gql, FragmentType } from \"@apollo/client\";\nimport { useSuspenseFragment } from \"@apollo/client/react\";\n\n// Fragment definition\n// This will be picked up by Codegen to create `UserCard_UserFragmentDoc` in `./fragments.generated.ts`.\n// As that generated fragment document is correctly typed, we use that in the code going forward.\n// This fragment will never be consumed in runtime code, so it is wrapped in `if (false)` so the bundler can omit it when bundling.\nif (false) {\n gql`\n fragment UserCard_user on User {\n id\n name\n email\n avatarUrl\n }\n `;\n}\n\n// This has been created from above fragment definition by CodeGen and is a correctly typed `TypedDocumentNode`\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated.ts\";\n\n// Component receives the (partially masked) parent object\nexport function UserCard({\n user,\n}: {\n user: FragmentType\n 
\n
\n );\n}\n```\n\n### Naming Convention\n\nA suggested naming pattern for fragments follows this convention:\n\n```text\n{ComponentName}_{propName}\n```\n\nWhere `propName` is the name of the prop the component receives containing the fragment data.\n\nExamples:\n\n- `UserCard_user` - Fragment for the `user` prop in the UserCard component\n- `PostList_posts` - Fragment for the `posts` prop in the PostList component\n- `CommentItem_comment` - Fragment for the `comment` prop in the CommentItem component\n\nThis convention makes it clear which component owns which fragment. However, you can choose a different naming convention based on your project's needs.\n\n**Note**: A component might accept fragment data through multiple props, in which case it would have multiple associated fragments. For example, a `CommentCard` component might accept both a `comment` prop and an `author` prop, resulting in `CommentCard_comment` and `CommentCard_author` fragments.\n\n### Composing Fragments\n\nParent components compose child fragments to build complete queries:\n\n```tsx\n// Child component\nimport { gql } from \"@apollo/client\";\n\nif (false) {\n gql`\n fragment UserAvatar_user on User {\n id\n avatarUrl\n name\n }\n `;\n}\n\n// Parent component composes child fragments\nif (false) {\n gql`\n fragment UserProfile_user on User {\n id\n name\n email\n bio\n ...UserAvatar_user\n }\n `;\n}\n\n// Page-level query composes all fragments\nif (false) {\n gql`\n query UserProfilePage($id: ID!) {\n user(id: $id) {\n ...UserProfile_user\n }\n }\n `;\n}\n```\n\nThis creates a hierarchy that mirrors your component tree.\n\n## Fragment Reading Hooks\n\nApollo Client provides hooks to read fragment data within components. These hooks work with data masking to ensure components only access the data they explicitly requested.\n\n### useSuspenseFragment\n\nFor components using Suspense and concurrent features:\n\n```tsx\nimport { useSuspenseFragment } from \"@apollo/client/react\";\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.name}
\n{data.email}
\n{data.name}
;\n}\n```\n\n### useFragment\n\nFor components not using Suspense:\n\n```tsx\nimport { useFragment } from \"@apollo/client/react\";\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentTypeLoading...
;\n }\n\n return {data.name}
;\n}\n```\n\nThe `complete` field indicates whether all fragment data is available in the cache.\n\n### Hook Options\n\nBoth hooks accept these options:\n\n```typescript\n{\n // The fragment document (required)\n fragment: TypedDocumentNode,\n\n // The fragment name (optional in most cases)\n // Only required if the fragment document contains multiple definitions\n fragmentName?: string,\n\n // The source data containing the fragment (required)\n // Can be a single object or an array of objects\n from: FragmentType{user.privateData}
;\n}\n```\n\nWith data masking:\n\n```tsx\n// ✅ With data masking - component can only access its fragment data\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.privateData}
;\n\n // Only fields from the fragment are accessible\n return {data.name}
;\n}\n```\n\n### Benefits of Data Masking\n\n- **Prevents over-rendering**: Components only re-render when their specific data changes\n- **Enforces boundaries**: Components can't accidentally depend on data they don't own\n- **Better refactoring**: Safe to modify parent queries without breaking child components\n- **Type safety**: TypeScript catches attempts to access unavailable fields\n\n## Fragment Registry\n\nThe fragment registry is an **alternative approach** to GraphQL Code Generator's automatic fragment inlining by name. It allows you to register fragments globally, making them available throughout your application by name reference.\n\n**Important**: GraphQL Code Generator automatically inlines fragments by name wherever they're used in your queries. Either approach is sufficient on its own—**you don't need to combine them**.\n\n### Creating a Fragment Registry\n\n```typescript\nimport { ApolloClient, InMemoryCache } from \"@apollo/client\";\nimport { createFragmentRegistry } from \"@apollo/client/cache\";\n\nexport const fragmentRegistry = createFragmentRegistry();\n\nconst client = new ApolloClient({\n cache: new InMemoryCache({\n fragments: fragmentRegistry,\n }),\n});\n```\n\n### Registering Fragments\n\nRegister fragments after defining them:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { fragmentRegistry } from \"./apollo/client\";\n\nconst USER_FRAGMENT = gql`\n fragment UserFields on User {\n id\n name\n email\n }\n`;\n\nfragmentRegistry.register(USER_FRAGMENT);\n```\n\nWith colocated fragments:\n\n```tsx\nimport { fragmentRegistry } from \"@/apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\n// Register the fragment globally\nfragmentRegistry.register(UserCard_UserFragmentDoc);\n```\n\n### Using Registered Fragments\n\nOnce registered, fragments can be referenced by name in queries without explicit imports:\n\n```tsx\n// Fragment is available by name because it's registered\nconst GET_USER = gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n ...UserCard_user\n }\n }\n`;\n```\n\n### Approaches for Fragment Composition\n\nThere are three approaches to make child fragments available in parent queries:\n\n1. **GraphQL Code Generator inlining** (Recommended): CodeGen automatically inlines fragments by name. No manual work needed—just reference fragments by name in your queries.\n\n2. **Fragment Registry**: Manually register fragments to make them available by name. Useful for runtime scenarios where CodeGen isn't available.\n\n3. **Manual interpolation**: Explicitly import and interpolate child fragments into parent fragments:\n\n ```typescript\n import { CHILD_FRAGMENT } from \"./ChildComponent\";\n\n const PARENT_FRAGMENT = gql`\n fragment Parent_data on Data {\n field\n ...Child_data\n }\n ${CHILD_FRAGMENT}\n `;\n ```\n\n### Pros and Cons\n\n**GraphQL Code Generator inlining**:\n\n- ✅ Less work: Automatic, no manual registration needed\n- ❌ Larger bundle: Fragments are inlined into every query that uses them\n\n**Fragment Registry**:\n\n- ✅ Smaller bundle: Fragments are registered once, referenced by name\n- ❌ More work: Requires manual registration of each fragment\n- ❌ May cause issues with lazy-loaded modules if the module is not loaded before the query is executed\n- ✅ Best for deeply nested component trees where bundle size matters\n\n**Manual interpolation**:\n\n- ❌ Most work: Manual imports and interpolation required\n- ✅ Explicit: Clear fragment dependencies in code\n\n### Recommendation\n\nFor most applications using GraphQL Code Generator (as shown in this guide), **use the automatic inlining**—it requires no additional setup and works seamlessly. Consider the fragment registry only if bundle size becomes a concern in applications with deeply nested component trees.\n\n## TypeScript Integration\n\nApollo Client provides strong TypeScript support for fragments through GraphQL Code Generator.\n\n### Generated Types\n\nGraphQL Code Generator produces typed fragment documents:\n\n```typescript\n// Generated file: fragments.generated.ts\nexport type UserCard_UserFragment = {\n __typename: \"User\";\n id: string;\n name: string;\n email: string;\n avatarUrl: string;\n} & { \" $fragmentName\"?: \"UserCard_UserFragment\" };\n\nexport const UserCard_UserFragmentDoc: TypedDocumentNode<\n UserCard_UserFragment,\n never\n>;\n```\n\n### Type-Safe Fragment Usage\n\nUse `FragmentType` to accept masked fragment data:\n\n```tsx\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.name}
;\n}\n```\n\n### Fragment Type Inference\n\nTypeScript infers types from fragment documents automatically:\n\n```tsx\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\n// Types are inferred from the fragment\nconst { data } = useSuspenseFragment({\n fragment: UserCard_UserFragmentDoc,\n from: user,\n});\n\n// data.name is string\n// data.email is string\n// data.nonExistentField is a TypeScript error\n```\n\n### Parent-Child Type Safety\n\nWhen passing fragment data from parent to child:\n\n```tsx\n// Parent query\nconst { data } = useSuspenseQuery(GET_USER);\n\n// TypeScript ensures the query includes UserCard_user fragment\n// before allowing it to be passed to UserCard\n{data.name}
;\n}\n```\n\n```tsx\n// ❌ Avoid: Component uses query hook\nfunction UserCard({ userId }: { userId: string }) {\n const { data } = useQuery(GET_USER, { variables: { id: userId } });\n return {data.user.name}
;\n}\n```\n\n### Request Only Required Fields\n\nKeep fragments minimal and only request fields the component actually uses:\n\n```tsx\n// ✅ Good: Only necessary fields\nif (false) {\n gql`\n fragment UserListItem_user on User {\n id\n name\n }\n `;\n}\n```\n\n```tsx\n// ❌ Avoid: Requesting unused fields\nif (false) {\n gql`\n fragment UserListItem_user on User {\n id\n name\n email\n bio\n friends {\n id\n name\n }\n posts {\n id\n title\n }\n }\n `;\n}\n```\n\n### Use @defer for Below-the-Fold Content\n\nThe `@defer` directive allows you to defer loading of non-critical fields, enabling faster initial page loads by prioritizing essential data. The deferred fields are delivered via incremental delivery and arrive after the non-deferred data, allowing the UI to progressively render as data becomes available.\n\nDefer slow fields that aren't immediately visible:\n\n```tsx\nif (false) {\n gql`\n query ProductPage($id: ID!) {\n product(id: $id) {\n id\n name\n price\n ...ProductReviews_product @defer\n }\n }\n `;\n}\n```\n\nThis allows the page to render quickly while reviews load in the background.\n\n### Handle Client-Only Fields\n\nUse the `@client` directive for fields resolved locally:\n\n```tsx\nif (false) {\n gql`\n fragment TodoItem_todo on Todo {\n id\n text\n completed\n isSelected @client\n }\n `;\n}\n```\n\n### Enable Data Masking for New Applications\n\nAlways enable data masking in new applications:\n\n```typescript\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n dataMasking: true,\n});\n```\n\nThis enforces proper boundaries from the start and prevents accidental coupling between components.\n\n## Apollo Client Data Masking vs GraphQL-Codegen Fragment Masking\n\nApollo Client's data masking and GraphQL Code Generator's fragment masking are different features that serve different purposes:\n\n### GraphQL-Codegen Fragment Masking\n\nGraphQL Code Generator's fragment masking (when using the client preset) is a **type-level** feature:\n\n- Masks data only at the TypeScript type level\n- The actual runtime data remains fully accessible on the object\n- Using their `useFragment` hook simply \"unmasks\" the data on a type level\n- Does not prevent accidental access to data at runtime\n- Parent components receive all data and pass it down\n- This means the parent component has to be subscribed to all data\n\n### Apollo Client Data Masking\n\nApollo Client's data masking is a **runtime** feature with significant performance benefits:\n\n- Removes data at the runtime level, not just the type level\n- The `useFragment` and `useSuspenseFragment` hooks create cache subscriptions\n- Parent objects are sparse and only contain unmasked data\n- Prevents accidental access to data that should be masked\n\n### Key Benefits of Apollo Client Data Masking\n\n**1. No Accidental Data Access**\n\nWith runtime data masking, masked fields are not present in the parent object at all. You cannot accidentally access them, even if you bypass TypeScript type checking.\n\n**2. Fewer Re-renders**\n\nApollo Client's approach creates more efficient subscriptions:\n\n- **Without data masking**: Parent component subscribes to all fields (including masked ones). When a masked child field changes, the parent re-renders to pass that runtime data down the tree.\n- **With data masking**: Parent component only subscribes to its own unmasked fields. Subscriptions on masked fields happen lower in the React component tree when the child component calls `useSuspenseFragment`. When a masked field changes, only the child component that subscribed to it re-renders.\n\n### Example\n\n```tsx\nimport { FragmentType } from \"@apollo/client\";\nimport { useSuspenseQuery, useSuspenseFragment } from \"@apollo/client/react\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction ParentComponent() {\n const { data } = useSuspenseQuery(GET_USER);\n\n // With Apollo Client data masking:\n // - data.user only contains unmasked fields\n // - Parent doesn't re-render when child-specific fields change\n\n return {data.name}
;\n}\n```\n\nThis granular subscription approach improves performance in large applications with deeply nested component trees.\n","docs/agent-skills/apollo-client/references/integration-client.md":"# Apollo Client Integration for Client-Side Apps\n\nThis guide covers setting up Apollo Client in client-side React applications without server-side rendering (SSR). This includes applications using Vite, Parcel, Create React App, or other bundlers that don't implement SSR.\n\nFor applications with SSR, use one of the framework-specific integration guides instead:\n\n- [Next.js App Router](integration-nextjs.md)\n- [React Router Framework Mode](integration-react-router.md)\n- [TanStack Start](integration-tanstack-start.md)\n\n## Installation\n\n```bash\nnpm install @apollo/client graphql rxjs\n```\n\n## TypeScript Code Generation (optional but recommended)\n\nFor type-safe GraphQL operations with TypeScript, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\n## Setup Steps\n\n### Step 1: Create Client\n\n```typescript\nimport { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\";\n\n// Recommended: Use HttpOnly cookies for authentication\nconst httpLink = new HttpLink({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n credentials: \"include\", // Sends cookies with requests (secure when using HttpOnly cookies)\n});\n\nconst client = new ApolloClient({\n link: httpLink,\n cache: new InMemoryCache(),\n});\n```\n\nIf you need manual token management (less secure, only when HttpOnly cookies aren't available):\n\n```typescript\nimport { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\";\nimport { SetContextLink } from \"@apollo/client/link/context\";\n\nconst httpLink = new HttpLink({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n});\n\nconst authLink = new SetContextLink(({ headers }) => {\n const token = localStorage.getItem(\"token\");\n return {\n headers: {\n ...headers,\n authorization: token ? `Bearer ${token}` : \"\",\n },\n };\n});\n\nconst client = new ApolloClient({\n link: authLink.concat(httpLink),\n cache: new InMemoryCache(),\n});\n```\n\n### Step 2: Setup Provider\n\n```tsx\nimport { ApolloProvider } from \"@apollo/client\";\nimport App from \"./App\";\n\nfunction Root() {\n return (\n Loading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return (\n- {data?.users.map((user) =>
- {user.name} )}
Loading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return{data?.user.name}
;\n}\n```\n\n> **Note for TypeScript users**: Use [`dataState`](https://www.apollographql.com/docs/react/data/typescript#type-narrowing-data-with-datastate) for more robust type safety and better type narrowing in Apollo Client 4.x.\n\n### TypeScript Integration\n\nFor complete examples with loading, error handling, and `dataState` for type narrowing, see [Basic Query Usage](#basic-query-usage) above.\n\n#### Usage with Generated Types\n\nFor type-safe operations with code generation, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\nQuick example:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useQuery } from \"@apollo/client/react\";\nimport { GetUserDocument } from \"./queries.generated\";\n\n// Define your query with the if (false) pattern for code generation\nif (false) {\n gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n id\n name\n email\n }\n }\n `;\n}\n\nfunction UserProfile({ userId }: { userId: string }) {\n // Types are automatically inferred from GetUserDocument\n const { data } = useQuery(GetUserDocument, {\n variables: { id: userId },\n });\n\n return {data.user.name}
;\n}\n```\n\n#### Usage with Manual Type Annotations\n\nIf not using code generation, define types alongside your queries using `TypedDocumentNode`:\n\n```typescript\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\nimport { useQuery } from \"@apollo/client/react\";\n\ninterface GetUserData {\n user: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface GetUserVariables {\n id: string;\n}\n\n// Types should always be defined via TypedDocumentNode alongside your queries/mutations, not at the useQuery/useMutation call site\nconst GET_USER: TypedDocumentNode{data.user.name}
;\n}\n```\n\n## Basic Mutation Usage\n\n```tsx\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\nimport { useMutation } from \"@apollo/client/react\";\n\ninterface CreateUserMutation {\n createUser: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface CreateUserMutationVariables {\n input: {\n name: string;\n email: string;\n };\n}\n\nconst CREATE_USER: TypedDocumentNode<\n CreateUserMutation,\n CreateUserMutationVariables\n> = gql`\n mutation CreateUser($input: CreateUserInput!) {\n createUser(input: $input) {\n id\n name\n email\n }\n }\n`;\n\nfunction CreateUserForm() {\n const [createUser, { loading, error }] = useMutation(CREATE_USER);\n\n const handleSubmit = async (formData: FormData) => {\n const { data } = await createUser({\n variables: {\n input: {\n name: formData.get(\"name\") as string,\n email: formData.get(\"email\") as string,\n },\n },\n });\n if (data) {\n console.log(\"Created user:\", data.createUser);\n }\n };\n\n return (\n Error: {error.message}
}\n \n );\n}\n```\n\n## Client Configuration Options\n\n```typescript\nconst client = new ApolloClient({\n // Required: The cache implementation\n cache: new InMemoryCache({\n typePolicies: {\n Query: {\n fields: {\n // Field-level cache configuration\n },\n },\n },\n }),\n\n // Network layer\n link: new HttpLink({ uri: \"/graphql\" }),\n\n // Avoid defaultOptions if possible as they break TypeScript expectations.\n // Configure options per-query/mutation instead for better type safety.\n // defaultOptions: {\n // watchQuery: { fetchPolicy: 'cache-and-network' },\n // },\n\n // DevTools are enabled by default in development\n // Only configure when enabling in production\n devtools: {\n enabled: true, // Only needed for production\n },\n\n // Custom name for this client instance\n clientAwareness: {\n name: \"web-client\",\n version: \"1.0.0\",\n },\n});\n```\n\n## Important Considerations\n\n1. **Choose Your Hook Strategy:** Decide if your application should be based on Suspense. If it is, use suspenseful hooks like `useSuspenseQuery` (see [Suspense Hooks guide](suspense-hooks.md)), otherwise use non-suspenseful hooks like `useQuery` (see [Queries guide](queries.md)).\n\n2. **Client-Side Only:** This setup is for client-side apps without SSR. The Apollo Client instance is created once and reused throughout the application lifecycle.\n\n3. **Authentication:** Prefer HttpOnly cookies with `credentials: \"include\"` in `HttpLink` options to avoid exposing tokens to JavaScript. If manual token management is necessary, use `SetContextLink` to dynamically add authentication headers from `localStorage` or other client-side storage.\n\n4. **Environment Variables:** Store your GraphQL endpoint URL in environment variables for different environments (development, staging, production).\n\n5. **Error Handling:** Always handle `loading` and `error` states when using `useQuery` or `useLazyQuery`. For Suspense-based hooks (`useSuspenseQuery`), React handles this through `{data.user.name}
;\n}\n```\n\n### Override Next.js Fetch Options\n\nYou can override Next.js-specific `fetch` options per query using `context.fetchOptions`:\n\n```typescript\nconst { data } = await getClient().query({\n query: GET_USER,\n context: {\n fetchOptions: {\n next: { revalidate: 60 }, // Revalidate every 60 seconds\n },\n },\n});\n```\n\n## Setup for Client Components (SSR and Browser)\n\n### Step 1: Create Apollo Wrapper Component\n\nCreate `app/ApolloWrapper.tsx`:\n\n```typescript\n\"use client\";\n\nimport { HttpLink } from \"@apollo/client\";\nimport {\n ApolloNextAppProvider,\n ApolloClient,\n InMemoryCache,\n} from \"@apollo/client-integration-nextjs\";\n\nfunction makeClient() {\n const httpLink = new HttpLink({\n // Use an absolute URL for SSR\n uri: \"https://your-api.com/graphql\",\n fetchOptions: {\n // Optional: Next.js-specific fetch options\n // Note: This doesn't work with `export const dynamic = \"force-static\"`\n },\n });\n\n return new ApolloClient({\n cache: new InMemoryCache(),\n link: httpLink,\n });\n}\n\nexport function ApolloWrapper({ children }: React.PropsWithChildren) {\n return (\n {data.user.name}
;\n}\n```\n\n## Preloading Data from RSC to Client Components\n\nYou can preload data in React Server Components to populate the cache of your Client Components.\n\n### Step 1: Use PreloadQuery in Server Components\n\n```tsx\nimport { PreloadQuery } from \"./ApolloClient\";\nimport { Suspense } from \"react\";\n\nexport default async function Page() {\n return (\n {data.user.name}
;\n}\n```\n\n> **Important:** Data fetched this way should be considered client data and never referenced in Server Components. `PreloadQuery` prevents mixing server data and client data by creating a separate `ApolloClient` instance.\n\n### Using with useReadQuery\n\nFor advanced use cases, you can use `PreloadQuery` with `useReadQuery` to avoid request waterfalls:\n\n```tsx\n{data.user.name}
;\n}\n```\n\n## Handling Multipart Responses (@defer) in SSR\n\nWhen using the `@defer` directive, `useSuspenseQuery` will only suspend until the initial response is received. To handle deferred data properly, you have three strategies:\n\n### Strategy 1: Use PreloadQuery with useReadQuery\n\n`PreloadQuery` allows deferred data to be fully transported and streamed chunk-by-chunk.\n\n### Strategy 2: Remove @defer Fragments\n\nUse `RemoveMultipartDirectivesLink` to strip `@defer` directives from queries during SSR:\n\n```typescript\nimport { RemoveMultipartDirectivesLink } from \"@apollo/client-integration-nextjs\";\n\nnew RemoveMultipartDirectivesLink({\n stripDefer: true, // Default: true\n});\n```\n\nYou can exclude specific fragments from stripping by labeling them:\n\n```graphql\nquery myQuery {\n fastField\n ... @defer(label: \"SsrDontStrip1\") {\n slowField1\n }\n}\n```\n\n### Strategy 3: Wait for Deferred Data\n\nUse `AccumulateMultipartResponsesLink` to debounce the initial response:\n\n```typescript\nimport { AccumulateMultipartResponsesLink } from \"@apollo/client-integration-nextjs\";\n\nnew AccumulateMultipartResponsesLink({\n cutoffDelay: 100, // Wait up to 100ms for incremental data\n});\n```\n\n### Combined Approach: SSRMultipartLink\n\nCombine both strategies with `SSRMultipartLink`:\n\n```typescript\nimport { SSRMultipartLink } from \"@apollo/client-integration-nextjs\";\n\nnew SSRMultipartLink({\n stripDefer: true,\n cutoffDelay: 100,\n});\n```\n\n## Testing\n\nReset singleton instances between tests using the `resetApolloClientSingletons` helper:\n\n```typescript\nimport { resetApolloClientSingletons } from \"@apollo/client-integration-nextjs\";\n\nafterEach(resetApolloClientSingletons);\n```\n\n## Debugging\n\nEnable verbose logging in your `app/ApolloWrapper.tsx`:\n\n```typescript\nimport { setLogVerbosity } from \"@apollo/client\";\n\nsetLogVerbosity(\"debug\");\n```\n\n## Important Considerations\n\n1. **Separate RSC and SSR Queries:** Avoid overlapping queries between RSC and SSR. RSC queries don't update in the browser, while SSR queries can update dynamically as the cache changes.\n\n2. **Use Absolute URLs:** Always use absolute URLs in `HttpLink` for SSR, as relative URLs cannot be used in server-side rendering.\n\n3. **Streaming SSR:** For optimal performance, use `useSuspenseQuery` and `useFragment` to take advantage of React 18's streaming SSR capabilities.\n\n4. **Suspense Boundaries:** Place `Suspense` boundaries at meaningful places in your UI for the best user experience.\n","docs/agent-skills/apollo-client/references/integration-react-router.md":"# Apollo Client Integration with React Router Framework Mode\n\nThis guide covers integrating Apollo Client in a React Router 7 application with support for modern streaming SSR.\n\n## Installation\n\nInstall Apollo Client and the React Router integration package:\n\n```bash\nnpm install @apollo/client-integration-react-router @apollo/client graphql rxjs\n```\n\n> **TypeScript users:** For type-safe GraphQL operations, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\n## Setup\n\n### Step 1: Create Apollo Configuration\n\nCreate an `app/apollo.ts` file that exports a `makeClient` function and an `apolloLoader`:\n\n```typescript\nimport { HttpLink, InMemoryCache } from \"@apollo/client\";\nimport {\n createApolloLoaderHandler,\n ApolloClient,\n} from \"@apollo/client-integration-react-router\";\n\n// `request` will be available on the server during SSR or in loaders, but not in the browser\nexport const makeClient = (request?: Request) => {\n return new ApolloClient({\n cache: new InMemoryCache(),\n link: new HttpLink({ uri: \"https://your-graphql-endpoint.com/graphql\" }),\n });\n};\n\nexport const apolloLoader = createApolloLoaderHandler(makeClient);\n```\n\n> **Important:** `ApolloClient` must be imported from `@apollo/client-integration-react-router`, not from `@apollo/client`.\n\n### Step 2: Reveal Entry Files\n\nRun the following command to create the entry files if they don't exist:\n\n```bash\nnpx react-router reveal\n```\n\nThis will create `app/entry.client.tsx` and `app/entry.server.tsx`.\n\n### Step 3: Configure Client Entry\n\nAdjust `app/entry.client.tsx` to wrap your app in `ApolloProvider`:\n\n```typescript\nimport { makeClient } from \"./apollo\";\nimport { ApolloProvider } from \"@apollo/client\";\nimport { StrictMode, startTransition } from \"react\";\nimport { hydrateRoot } from \"react-dom/client\";\nimport { HydratedRouter } from \"react-router/dom\";\n\nstartTransition(() => {\n const client = makeClient();\n hydrateRoot(\n document,\n \n
\n );\n}\n```\n\n> **Important:** To provide better TypeScript support, `apolloLoader` is a method that you need to call twice: `apolloLoader{data.user.name}
\n{data.user.email}
\n\n
\n );\n}\n```\n\n## Important Considerations\n\n1. **Import ApolloClient from Integration Package:** Always import `ApolloClient` from `@apollo/client-integration-react-router`, not from `@apollo/client`, to ensure proper SSR hydration.\n\n2. **TypeScript Support:** The `apolloLoader` function requires double invocation for proper TypeScript type inference: `apolloLoader{userData.user.name}
\nPosts
\n- \n {postsData.posts.map((post) => (\n
- {post.title} \n ))}\n
\n
\n );\n}\n```\n\n### Option 2: Direct useSuspenseQuery in Component\n\nYou can also use Apollo Client's suspenseful hooks directly in your component without a loader:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\nimport { createFileRoute } from \"@tanstack/react-router\";\nimport type { TypedDocumentNode } from \"@apollo/client\";\n\n// TypedDocumentNode definition with types\nconst GET_POSTS: TypedDocumentNode<{\n posts: Array<{ id: string; title: string; content: string }>;\n}> = gql`\n query GetPosts {\n posts {\n id\n title\n content\n }\n }\n`;\n\nexport const Route = createFileRoute(\"/posts\")({\n component: RouteComponent,\n});\n\nfunction RouteComponent() {\n const { data } = useSuspenseQuery(GET_POSTS);\n\n return (\n {data.user.name}
\n{data.user.email}
\n\n
\n );\n}\n```\n\n### Multiple Queries in a Loader\n\nYou can preload multiple queries in a single loader:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useReadQuery } from \"@apollo/client/react\";\nimport { createFileRoute } from \"@tanstack/react-router\";\n\n// TypedDocumentNode definitions omitted for brevity\n\nexport const Route = createFileRoute(\"/dashboard\")({\n component: RouteComponent,\n loader: ({ context: { preloadQuery } }) => {\n const userQueryRef = preloadQuery(GET_USER, {\n variables: { id: \"current\" },\n });\n\n const statsQueryRef = preloadQuery(GET_STATS, {\n variables: { period: \"month\" },\n });\n\n return {\n userQueryRef,\n statsQueryRef,\n };\n },\n});\n\nfunction RouteComponent() {\n const { userQueryRef, statsQueryRef } = Route.useLoaderData();\n const { data: userData } = useReadQuery(userQueryRef);\n const { data: statsData } = useReadQuery(statsQueryRef);\n\n return (\n Posts
\n- \n {data.posts.map((post) => (\n
- \n
{post.title}
\n{post.content}
\n \n ))}\n
\n
\n );\n}\n```\n\n### Using useQueryRefHandlers for Refetching\n\nWhen using `useReadQuery`, you can get refetch functionality from `useQueryRefHandlers`:\n\n> **Important:** Always call `useQueryRefHandlers` before `useReadQuery`. These two hooks interact with the same `queryRef`, and calling them in the wrong order could cause subtle bugs.\n\n```typescript\nimport { useReadQuery, useQueryRefHandlers, QueryRef } from \"@apollo/client/react\";\n\nfunction UserComponent({ queryRef }: { queryRef: QueryRefWelcome, {userData.user.name}
\n\n
\n Monthly Stats
\nViews: {statsData.stats.views}
\nClicks: {statsData.stats.clicks}
\n\n
\n );\n}\n```\n\n## Important Considerations\n\n1. **Import from Integration Package:** Always import `ApolloClient` and `InMemoryCache` from `@apollo/client-integration-tanstack-start`, not from `@apollo/client`, to ensure proper SSR hydration.\n\n2. **Context Type:** Use `createRootRouteWithContext{data.user.name}
\n \nError: {error.message}
}\n \n );\n}\n```\n\n### Return Tuple\n\n```typescript\nconst [\n mutateFunction, // Function to call to execute mutation\n {\n data, // Mutation result data\n loading, // True while mutation is in flight\n error, // ApolloError if mutation failed\n called, // True if mutation has been called\n reset, // Reset mutation state\n client, // Apollo Client instance\n },\n] = useMutation(MUTATION);\n```\n\n## Mutation Variables\n\n### Variables in Options\n\n```tsx\nconst [createUser] = useMutation(CREATE_USER, {\n variables: {\n input: {\n name: \"Default User\",\n email: \"default@example.com\",\n },\n },\n});\n\n// Call with default variables\nawait createUser();\n\n// Override variables\nawait createUser({\n variables: {\n input: {\n name: \"Custom User\",\n email: \"custom@example.com\",\n },\n },\n});\n```\n\n### TypeScript Types\n\nUse `TypedDocumentNode` instead of generic type parameters:\n\n```typescript\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\n\ninterface CreateUserData {\n createUser: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface CreateUserVariables {\n input: {\n name: string;\n email: string;\n };\n}\n\nconst CREATE_USER: TypedDocumentNode\n
\n );\n }\n\n return (\n \n );\n}\n```\n\n### Async/Await Pattern\n\nIf you only need the promise without using the hook's loading/data state, use `client.mutate` instead:\n\n```tsx\nimport { useApolloClient } from \"@apollo/client/react\";\n\nfunction CreatePost() {\n const client = useApolloClient();\n\n async function handleSubmit(formData: FormData) {\n try {\n const { data } = await client.mutate({\n mutation: CREATE_POST,\n variables: {\n input: {\n title: formData.get(\"title\"),\n content: formData.get(\"content\"),\n },\n },\n });\n console.log(\"Created:\", data.createPost);\n router.push(`/posts/${data.createPost.id}`);\n } catch (error) {\n console.error(\"Failed to create post:\", error);\n }\n }\n\n return (\n Post created: {data.createPost.title}
\n \nLoading...
;\n if (error) returnError: {error.message}
;\n\n return- {data?.dogs.map((dog) =>
- {dog.breed} )}
Error: {error.message}
;\n\n return\n {loading &&
\n );\n}\n```\n\n### Network Status\n\n```tsx\nimport { NetworkStatus } from \"@apollo/client\";\n\nfunction Dogs() {\n const { loading, error, data, networkStatus, refetch } = useQuery(GET_DOGS, {\n notifyOnNetworkStatusChange: true,\n });\n\n if (networkStatus === NetworkStatus.refetch) {\n return Refetching...
;\n }\n\n if (loading) returnLoading...
;\n if (error) returnError: {error.message}
;\n\n return (\n <>\n \n- \n {data.dogs.map((dog) => (\n
- {dog.breed} \n ))}\n
Loading...
;\n if (error) returnError: {error.message}
;\n\n return (\n\n {data?.dog && 
}\n \n
\n );\n}\n```\n\n### When to Use client.query Instead\n\nIf you only need the promise result and don't consume the loading/error/data states from the hook, use `client.query` instead:\n\n```tsx\nimport { useApolloClient } from \"@apollo/client/react\";\n\nfunction SearchDogs() {\n const client = useApolloClient();\n const [search, setSearch] = useState(\"\");\n\n const handleSearch = async () => {\n try {\n const { data } = await client.query({\n query: SEARCH_DOGS,\n variables: { query: search },\n });\n console.log(\"Found dogs:\", data.searchDogs);\n } catch (error) {\n console.error(\"Search failed:\", error);\n }\n };\n\n return (\n \n setSearch(e.target.value)} />\n \n
\n );\n}\n```\n\n## Polling and Refetching\n\n### Polling\n\n```tsx\nfunction LiveFeed() {\n const { data, startPolling, stopPolling } = useQuery(GET_FEED, {\n pollInterval: 5000, // Poll every 5 seconds\n });\n\n // Or control polling dynamically\n useEffect(() => {\n startPolling(5000);\n return () => stopPolling();\n }, [startPolling, stopPolling]);\n\n return \n \n \n
\n );\n}\n```\n\n## Fetch Policies\n\nControl how the query interacts with the cache.\n\n| Policy | Description |\n| ------------------- | ---------------------------------------------------------- |\n| `cache-first` | Return cached data if available, otherwise fetch (default) |\n| `cache-only` | Only return cached data, never fetch |\n| `cache-and-network` | Return cached data immediately, then fetch and update |\n| `network-only` | Always fetch, update cache, ignore cached data |\n| `no-cache` | Always fetch, never read or write cache |\n| `standby` | Same as cache-first but doesn't auto-update |\n\n### Usage Examples\n\n```tsx\n// Real-time data - always fetch\nconst { data } = useQuery(GET_NOTIFICATIONS, {\n fetchPolicy: \"network-only\",\n});\n\n// Static data - prefer cache\nconst { data } = useQuery(GET_CATEGORIES, {\n fetchPolicy: \"cache-first\",\n});\n\n// Show cached data while fetching fresh data\nconst { data, loading } = useQuery(GET_POSTS, {\n fetchPolicy: \"cache-and-network\",\n});\n\n// Fetch once, then use cache\nconst { data } = useQuery(GET_USER_PROFILE, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: \"cache-first\",\n});\n```\n\n### nextFetchPolicy\n\n```tsx\n// First request: network-only\n// Subsequent requests: cache-first\nconst { data } = useQuery(GET_POSTS, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: \"cache-first\",\n});\n\n// Or use a function for more control\nconst { data } = useQuery(GET_POSTS, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: (currentFetchPolicy, { reason, observable }) => {\n if (reason === \"after-fetch\") {\n return \"cache-first\";\n }\n return currentFetchPolicy;\n },\n});\n```\n\n## Conditional Queries\n\n### Using skipToken (Recommended)\n\nUse `skipToken` to conditionally skip queries without TypeScript issues:\n\n```tsx\nimport { skipToken } from \"@apollo/client\";\n\nfunction UserProfile({ userId }: { userId: string | null }) {\n const { data } = useQuery(\n GET_USER,\n !userId ? skipToken : (\n {\n variables: { id: userId },\n }\n )\n );\n\n return userId ? - {data?.dogs.map((dog) =>
- {dog.breed} )}
Select a user
;\n}\n```\n\n### Skip Option (Alternative)\n\n```tsx\nfunction UserProfile({ userId }: { userId: string | null }) {\n const { data } = useQuery(GET_USER, {\n variables: { id: userId! },\n skip: !userId, // Don't execute if no userId\n });\n\n return userId ?Select a user
;\n}\n```\n\n> **Note**: Using `skipToken` is preferred over `skip` as it avoids TypeScript issues with required variables and the non-null assertion operator.\n\n### SSR Skip\n\n```tsx\n// Skip during server-side rendering\nconst { data } = useQuery(GET_USER_LOCATION, {\n skip: typeof window === \"undefined\",\n ssr: false,\n});\n```\n","docs/agent-skills/apollo-client/references/state-management.md":"# State Management Reference\n\n## Table of Contents\n\n- [Reactive Variables](#reactive-variables)\n- [Local-Only Fields](#local-only-fields)\n- [LocalState Resolvers](#localstate-resolvers)\n- [Combining Remote and Local State](#combining-remote-and-local-state)\n- [useReactiveVar Hook](#usereactivevar-hook)\n\n## Reactive Variables\n\nReactive variables are a way to store local state outside of the Apollo Client cache while still triggering reactive updates.\n\n**Important**: Reactive variables store a single value that notifies `ApolloClient` instances when changed. They do not have separate values per ApolloClient instance. In multi-user environments like SSR, global or module-level reactive variables could be shared between users and cause data leaks. In frameworks that use SSR, always avoid storing reactive variables as globals.\n\n### Creating Reactive Variables\n\n```typescript\nimport { makeVar } from \"@apollo/client\";\n\n// Simple reactive variable\nexport const isLoggedInVar = makeVar\n
\n );\n}\n```\n\n### Local Field Read Functions (Type Policies)\n\nLocal field `read` functions are defined in entity-level type policies. You can use reactive variables inside these `read` functions, along with other calculations or derived values:\n\n```typescript\nconst cache = new InMemoryCache({\n typePolicies: {\n User: {\n fields: {\n // Simple local field from reactive variable\n isSelected: {\n read(_, { readField }) {\n const id = readField(\"id\");\n return selectedUsersVar().includes(id);\n },\n },\n\n // Computed local field (derived value)\n displayName: {\n read(_, { readField }) {\n const name = readField(\"name\");\n const email = readField(\"email\");\n return name || email?.split(\"@\")[0] || \"Anonymous\";\n },\n },\n },\n },\n },\n});\n```\n\n## LocalState Resolvers\n\n### Query-Level Local Resolvers\n\nQuery-level local fields can be defined using `LocalState` resolvers. **Note**: Do not read reactive variables inside LocalState resolvers - this is not a documented/tested feature. It might not behave as expected.\n\n```typescript\nimport { LocalState } from \"@apollo/client/local-state\";\n\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n localState: new LocalState({\n resolvers: {\n Query: {\n // Read from localStorage\n theme: () => {\n if (typeof window !== \"undefined\") {\n return localStorage.getItem(\"theme\") || \"light\";\n }\n return \"light\";\n },\n\n // Read from cache\n currentUser: (_, __, { cache }) => {\n if (typeof window === \"undefined\") return null;\n const userId = localStorage.getItem(\"currentUserId\");\n if (!userId) return null;\n return cache.readFragment({\n id: cache.identify({ __typename: \"User\", id: userId }),\n fragment: gql`\n fragment CurrentUser on User {\n id\n name\n email\n }\n `,\n });\n },\n\n // Compute value\n isOnline: () => {\n if (typeof navigator !== \"undefined\") {\n return navigator.onLine;\n }\n return true;\n },\n },\n },\n }),\n});\n```\n\n### Using Local Query Fields\n\n```tsx\nconst GET_AUTH_STATE = gql`\n query GetAuthState {\n isLoggedIn @client\n currentUser @client {\n id\n name\n email\n }\n }\n`;\n\nfunction AuthStatus() {\n const { data } = useQuery(GET_AUTH_STATE);\n\n if (!data?.isLoggedIn) {\n return {data?.user.displayName}
\n{data?.user.email}
\n\n
\n );\n}\n```\n\n### Multiple Reactive Variables\n\n```tsx\nfunction AppLayout() {\n const theme = useReactiveVar(themeVar);\n const sidebarOpen = useReactiveVar(sidebarOpenVar);\n const isLoggedIn = useReactiveVar(isLoggedInVar);\n\n return (\n Items: {totalItems}
\nTotal: ${totalPrice.toFixed(2)}
\n\n {isLoggedIn && sidebarOpen && \n \n
\n );\n}\n```\n","docs/agent-skills/apollo-client/references/suspense-hooks.md":"# Suspense Hooks Reference\n\n> **Note**: Suspense hooks are the recommended approach for data fetching in modern React applications (React 18+). They provide cleaner code, better loading state handling, and enable streaming SSR.\n\n## Table of Contents\n\n- [useSuspenseQuery Hook](#usesuspensequery-hook)\n- [useBackgroundQuery and useReadQuery](#usebackgroundquery-and-usereadquery)\n- [useLoadableQuery](#useloadablequery)\n- [createQueryPreloader](#createquerypreloader)\n- [useQueryRefHandlers](#usequeryrefhandlers)\n- [Distinguishing Queries with queryKey](#distinguishing-queries-with-querykey)\n- [Suspense Boundaries and Error Handling](#suspense-boundaries-and-error-handling)\n- [Transitions](#transitions)\n- [Avoiding Request Waterfalls](#avoiding-request-waterfalls)\n- [Fetch Policies](#fetch-policies)\n- [Streaming SSR or React Server Components](#streaming-ssr-or-react-server-components)\n- [Conditional Queries](#conditional-queries)\n\n## useSuspenseQuery Hook\n\nThe `useSuspenseQuery` hook is the Suspense-ready replacement for `useQuery`. It initiates a network request and causes the component calling it to suspend while the request is made. Unlike `useQuery`, it does not return `loading` states—these are handled by React's Suspense boundaries and error boundaries.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\nimport { GET_DOG } from \"./queries.generated\";\n\nfunction App() {\n return (\n Name: {data.dog.name}
;\n}\n```\n\n### Return Object\n\n```typescript\nconst {\n data, // Query result data\n dataState, // With default options: \"complete\" | \"streaming\"\n // With returnPartialData: also \"partial\"\n // With errorPolicy \"all\" or \"ignore\": also \"empty\"\n error, // ApolloError (only when errorPolicy is \"all\" or \"ignore\")\n networkStatus, // NetworkStatus.ready, NetworkStatus.loading, etc.\n client, // Apollo Client instance\n refetch, // Function to re-execute query\n fetchMore, // Function for pagination\n} = useSuspenseQuery(QUERY, options);\n```\n\n### Key Differences from useQuery\n\n- **No `loading` boolean**: Component suspends instead of returning `loading: true`\n- **Error handling**: With default `errorPolicy` (`none`), errors are thrown and caught by error boundaries. With `errorPolicy: \"all\"` or `\"ignore\"`, the `error` property is returned and `data` may be `undefined`.\n- **`data` availability**: With default `errorPolicy` (`none`), `data` is guaranteed to be present when the component renders. With `errorPolicy: \"all\"` or `\"ignore\"`, when `dataState` is `empty`, `data` may be `undefined`.\n- **Suspense boundaries**: Must wrap component with `Name: {data.dog.name}
\n Breed: {data.dog.breed}
\n \n );\n}\n```\n\n### Rendering Partial Data\n\nUse `returnPartialData` to render immediately with partial cache data instead of suspending. The component will still suspend if there is no data in the cache.\n\n```tsx\nfunction Dog({ id }: { id: string }) {\n const { data } = useSuspenseQuery(GET_DOG, {\n variables: { id },\n returnPartialData: true,\n });\n\n return (\n <>\n Name: {data.dog?.name ?? \"Unknown\"}
\n {data.dog?.breed && Breed: {data.dog.breed}
}\n \n );\n}\n```\n\n## useBackgroundQuery and useReadQuery\n\nUse `useBackgroundQuery` with `useReadQuery` to avoid request waterfalls by starting a query in a parent component and reading the result in a child component. This pattern enables the parent to start fetching data before the child component renders.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useBackgroundQuery, useReadQuery } from \"@apollo/client/react\";\n\nfunction Parent() {\n // Start fetching immediately\n const [queryRef] = useBackgroundQuery(GET_DOG, {\n variables: { id: \"3\" },\n });\n\n return (\n Name: {data.dog.name}
;\n}\n```\n\n### When to Use\n\n- **Avoiding waterfalls**: Start fetching data in a parent (preferably above a suspense boundary) before child components render\n- **Preloading data**: Begin fetching before the component that needs the data is ready\n- **Parallel queries**: Start multiple queries at once in a parent component\n\n### Return Values\n\n`useBackgroundQuery` returns a tuple:\n\n```typescript\nconst [\n queryRef, // QueryRef to pass to useReadQuery\n { refetch, fetchMore, subscribeToMore }, // Helper functions\n] = useBackgroundQuery(QUERY, options);\n```\n\n`useReadQuery` returns the query result:\n\n```typescript\nconst {\n data, // Query result data (always defined)\n dataState, // \"complete\" | \"streaming\" | \"partial\" | \"empty\"\n error, // ApolloError (if errorPolicy allows)\n networkStatus, // Detailed network state (1-8)\n} = useReadQuery(queryRef);\n```\n\n## useLoadableQuery\n\nUse `useLoadableQuery` to imperatively load a query in response to a user interaction (like a button click) instead of on component mount.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useLoadableQuery, useReadQuery } from \"@apollo/client/react\";\nimport { GET_GREETING } from \"./queries.generated\";\n\nfunction App() {\n const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);\n\n return (\n <>\n {data.greeting.message}
;\n}\n```\n\n### Return Values\n\n```typescript\nconst [\n loadQuery, // Function to load the query\n queryRef, // QueryRef (null until loadQuery is called)\n { refetch, fetchMore, subscribeToMore, reset }, // Helper functions\n] = useLoadableQuery(QUERY, options);\n```\n\n### When to Use\n\n- **User-triggered fetching**: Load data in response to user actions\n- **Lazy loading**: Defer data fetching until it's actually needed\n- **Progressive disclosure**: Load data for UI elements that may not be initially visible\n\n## createQueryPreloader\n\nThe `createQueryPreloader` function creates a `preloadQuery` function that can be used to initiate queries outside of React components. This is useful for preloading data before a component renders, such as in route loaders or event handlers.\n\n### Basic Usage\n\n```tsx\nimport { ApolloClient, InMemoryCache } from \"@apollo/client\";\nimport { createQueryPreloader } from \"@apollo/client/react\";\n\nconst client = new ApolloClient({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n cache: new InMemoryCache(),\n});\n\n// Create a preload function\nexport const preloadQuery = createQueryPreloader(client);\n```\n\n### Using preloadQuery with Route Loaders\n\n> **Note**: This example applies to React Router in non-framework mode. For React Router framework mode, see [integration-react-router.md](./integration-react-router.md).\n\nUse the preload function with React Router's `loader` function to begin loading data during route transitions:\n\n```tsx\nimport { preloadQuery } from \"@/lib/apollo-client\";\nimport { GET_DOG } from \"./queries.generated\";\n\n// React Router loader function\nexport async function loader({ params }: { params: { id: string } }) {\n return preloadQuery({\n query: GET_DOG,\n variables: { id: params.id },\n });\n}\n\n// Route component\nexport default function DogRoute() {\n const queryRef = useLoaderData();\n\n return (\n \n
\n );\n}\n```\n\n### Preventing Route Transitions Until Query Loads\n\nUse `preloadQuery.toPromise(queryRef)` to prevent route transitions until the query finishes loading:\n\n```tsx\nexport async function loader({ params }: { params: { id: string } }) {\n const queryRef = preloadQuery({\n query: GET_DOG,\n variables: { id: params.id },\n });\n\n // Wait for the query to complete before transitioning\n return preloadQuery.toPromise(queryRef);\n}\n```\n\nWhen `preloadQuery.toPromise()` is used, the route transition waits for the query to complete, and the data renders immediately without showing a loading fallback.\n\n> **Note**: `preloadQuery.toPromise()` resolves with the `queryRef` itself (not the data) to encourage using `useReadQuery` for cache updates. If you need raw query data in your loader, use `client.query()` directly.\n\n### With Next.js Server Components\n\n> **Note**: For Next.js App Router, use the `PreloadQuery` component from `@apollo/client-integration-nextjs` instead. See [integration-nextjs.md](./integration-nextjs.md) for details.\n\n## useQueryRefHandlers\n\nThe `useQueryRefHandlers` hook provides access to `refetch` and `fetchMore` functions for queries initiated with `preloadQuery`, `useBackgroundQuery`, or `useLoadableQuery`. This is useful when you need to refetch or paginate data in components where the `queryRef` is passed through.\n\n> **Important:** Always call `useQueryRefHandlers` before `useReadQuery`. These two hooks interact with the same `queryRef`, and calling them in the wrong order could cause subtle bugs.\n\n### Basic Usage\n\n```tsx\nimport { useQueryRefHandlers } from \"@apollo/client/react\";\n\nfunction Breeds({ queryRef }: { queryRef: QueryRef{data.dog.name}
\nBreed: {data.dog.breed}
\n\n {\n startTransition(() => {\n refetch();\n });\n }}\n >\n {isPending ? \"Refetching...\" : \"Refetch breeds\"}\n \n
\n );\n}\n```\n\n### With Pagination\n\nUse `fetchMore` to implement pagination:\n\n```tsx\nfunction Posts({ queryRef }: { queryRef: QueryRef- \n {data.breeds.map((breed) => (\n
- {breed.name} \n ))}\n
\n {\n startTransition(() => {\n fetchMore({\n variables: {\n offset: data.posts.length,\n },\n });\n });\n }}\n >\n {isPending ? \"Loading...\" : \"Load more\"}\n \n
\n );\n}\n```\n\n### When to Use\n\n- **Preloaded queries**: Access refetch/fetchMore for queries initiated with `preloadQuery`\n- **Background queries**: Use in child components receiving `queryRef` from `useBackgroundQuery`\n- **Loadable queries**: Refetch or paginate queries initiated with `useLoadableQuery`\n- **React transitions**: Integrate with transitions to avoid showing loading fallbacks during refetches\n\n## Distinguishing Queries with queryKey\n\nApollo Client uses the combination of `query` and `variables` to uniquely identify each query. When multiple components use the same `query` and `variables`, they share the same identity and suspend at the same time, regardless of which component initiates the request.\n\nUse the `queryKey` option to ensure each hook has a unique identity:\n\n```tsx\nfunction UserProfile() {\n // First query with unique key\n const { data: userData } = useSuspenseQuery(GET_USER, {\n variables: { id: \"1\" },\n queryKey: [\"user-profile\"],\n });\n\n // Second query with same query and variables but different key\n const { data: userPreview } = useSuspenseQuery(GET_USER, {\n variables: { id: \"1\" },\n queryKey: [\"user-preview\"],\n });\n\n return (\n - \n {data.posts.map((post) => (\n
- {post.title} \n ))}\n
\n
\n );\n}\n```\n\n### When to Use\n\n- **Multiple instances**: When rendering multiple components that use the same query and variables\n- **Preventing shared suspension**: When you want independent control over when each query suspends\n- **Separate cache entries**: When you need to maintain separate cache states for the same query\n\n> **Note**: Each item in the `queryKey` array must be a stable identifier to prevent infinite fetches.\n\n## Suspense Boundaries and Error Handling\n\n### Suspense Boundaries\n\nWrap components that use Suspense hooks with `\n
\n )}\n >\n Something went wrong
\n{error.message}
\nName: {data?.dog?.name ?? \"Unknown\"}
\n {error && Warning: {error.message}
}\n \n );\n}\n```\n\n## Transitions\n\nUse React transitions to avoid showing loading UI when updating state. Transitions keep the previous UI visible while new data is fetching.\n\n### Using startTransition\n\n```tsx\nimport { useState, Suspense, startTransition } from \"react\";\n\nfunction DogSelector() {\n const { data } = useSuspenseQuery(GET_DOGS);\n const [selectedDog, setSelectedDog] = useState(data.dogs[0].id);\n\n return (\n <>\n User: {data.user.name}
;\n}\n\nfunction PostsList({ queryRef }: { queryRef: QueryRef- \n {data.posts.map((post) => (\n
- {post.title} \n ))}\n
Select a user
;\n }\n\n returnSelect a user
;\n }\n\n return (\n- {data?.users.map((user) =>
- {user.name} )}
{data.user.name}
;\n\n// Or use optional chaining\nreturn {data?.user?.name}
;\n```\n","docs/agent-skills/apollo-client/references/typescript-codegen.md":"# TypeScript Code Generation\n\nThis guide covers setting up GraphQL Code Generator for type-safe Apollo Client usage with TypeScript.\n\n## Installation\n\n```bash\nnpm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node\n```\n\n## Configuration\n\nCreate a `codegen.ts` file in your project root:\n\n```typescript\n// codegen.ts\nimport { CodegenConfig } from \"@graphql-codegen/cli\";\n\nconst config: CodegenConfig = {\n overwrite: true,\n schema: \"{data?.user.name}
;\n}\n```\n\n## Important Notes\n\n- The typed-document-node plugin might have a bundle size tradeoff but can prevent inconsistencies and is best suited for usage with LLMs, so it is recommended for most applications.\n- See the [GraphQL Code Generator documentation](https://www.apollographql.com/docs/react/development-testing/graphql-codegen#recommended-starter-configuration) for other recommended configuration patterns if required.\n- Apollo Client hooks automatically infer types from `TypedDocumentNode` - never use manual generics like `useQueryLoading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return{data?.user.name}
;\n}\n```\n\n### Basic Mutation\n\n```tsx\nimport { gql } from \"@apollo/client\";\nimport { useMutation } from \"@apollo/client/react\";\n\nconst CREATE_USER = gql`\n mutation CreateUser($input: CreateUserInput!) {\n createUser(input: $input) {\n id\n name\n }\n }\n`;\n\nfunction CreateUserForm() {\n const [createUser, { loading, error }] = useMutation(CREATE_USER);\n\n const handleSubmit = async (name: string) => {\n await createUser({ variables: { input: { name } } });\n };\n\n return ;\n}\n```\n\n### Suspense Query\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\n\nfunction UserProfile({ userId }: { userId: string }) {\n const { data } = useSuspenseQuery(GET_USER, {\n variables: { id: userId },\n });\n\n return {data.user.name}
;\n}\n\nfunction App() {\n return (\n \n {data?.posts.map((post) =>
\n );\n}\n```\n\n## Cache Manipulation\n\n### cache.readQuery\n\n```typescript\n// Read data from cache\nconst data = cache.readQuery({\n query: GET_TODOS,\n});\n\n// With variables\nconst userData = cache.readQuery({\n query: GET_USER,\n variables: { id: \"1\" },\n});\n```\n\n### cache.writeQuery\n\n```typescript\n// Write data to cache\ncache.writeQuery({\n query: GET_TODOS,\n data: {\n todos: [\n { __typename: \"Todo\", id: \"1\", text: \"Buy milk\", completed: false },\n ],\n },\n});\n\n// With variables\ncache.writeQuery({\n query: GET_USER,\n variables: { id: \"1\" },\n data: {\n user: { __typename: \"User\", id: \"1\", name: \"John\" },\n },\n});\n```\n\n### cache.readFragment / cache.writeFragment\n\n```typescript\n// Read a specific object - use cache.identify for safety\nconst user = cache.readFragment({\n id: cache.identify({ __typename: \"User\", id: \"1\" }),\n fragment: gql`\n fragment UserFragment on User {\n id\n name\n email\n }\n `,\n});\n\n// Apollo Client 4.1+: Use 'from' parameter (recommended)\nconst user = cache.readFragment({\n from: { __typename: \"User\", id: \"1\" },\n fragment: gql`\n fragment UserFragment on User {\n id\n name\n email\n }\n `,\n});\n\n// Update a specific object\ncache.writeFragment({\n id: cache.identify({ __typename: \"User\", id: \"1\" }),\n fragment: gql`\n fragment UpdateUser on User {\n name\n }\n `,\n data: {\n name: \"Jane\",\n },\n});\n\n// Apollo Client 4.1+: Use 'from' parameter (recommended)\ncache.writeFragment({\n from: { __typename: \"User\", id: \"1\" },\n fragment: gql`\n fragment UpdateUser on User {\n name\n }\n `,\n data: {\n name: \"Jane\",\n },\n});\n```\n\n### cache.modify\n\n```typescript\n// Modify fields directly\ncache.modify({\n id: cache.identify(user),\n fields: {\n // Set new value\n name: () => \"New Name\",\n\n // Transform existing value\n postCount: (existing) => existing + 1,\n\n // Delete field\n temporaryField: (_, { DELETE }) => DELETE,\n\n // Add to array\n friends: (existing, { toReference }) => [\n ...existing,\n toReference({ __typename: \"User\", id: \"2\" }),\n ],\n },\n});\n```\n\n### cache.evict\n\n```typescript\n// Remove object from cache\ncache.evict({ id: \"User:1\" });\n\n// Remove specific field\ncache.evict({ id: \"User:1\", fieldName: \"friends\" });\n\n// Remove with broadcast (trigger re-renders)\ncache.evict({ id: \"User:1\", broadcast: true });\n```\n\n## Garbage Collection\n\n### Manual Garbage Collection\n\n```typescript\n// After evicting objects, clean up dangling references\ncache.evict({ id: \"User:1\" });\ncache.gc();\n```\n\n### Retaining Objects\n\n```typescript\n// Prevent objects from being garbage collected\nconst release = cache.retain(\"User:1\");\n\n// Later, allow GC\nrelease();\ncache.gc();\n```\n\n### Inspecting Cache\n\n```typescript\n// Get all cached data\nconst cacheContents = cache.extract();\n\n// Restore cache state\ncache.restore(previousCacheContents);\n\n// Get identified object cache key\nconst userId = cache.identify({ __typename: \"User\", id: \"1\" });\n// Returns: 'User:1'\n```\n","docs/agent-skills/apollo-client/references/error-handling.md":"# Error Handling Reference (Apollo Client 4.x)\n\nNote that Apollo Client 4.x handles errors differently than Apollo Client 3.x.\nThis reference documents the updated error handling mechanisms, error types, and best practices for managing errors in your Apollo Client applications.\nFor older Apollo Client 3.x error handling documentation, see [Apollo Client 3.x Error Handling](https://www.apollographql.com/docs/react/v3/data/error-handling).\n\n## Table of Contents\n\n- [Understanding Errors](#understanding-errors)\n- [Error Types](#error-types)\n- [Identifying Error Types](#identifying-error-types)\n- [GraphQL Error Policies](#graphql-error-policies)\n- [Error Links](#error-links)\n- [Retry Link](#retry-link)\n- [Error Boundaries](#error-boundaries)\n\n## Understanding Errors\n\nErrors in Apollo Client fall into two main categories: **GraphQL errors** and **network errors**. Each category has specific error classes that provide detailed information about what went wrong.\n\n### GraphQL Errors\n\nGraphQL errors are related to server-side execution of a GraphQL operation:\n\n- **Syntax errors** (e.g., malformed query)\n- **Validation errors** (e.g., query includes a non-existent schema field)\n- **Resolver errors** (e.g., error while populating a query field)\n\nIf a syntax or validation error occurs, the server doesn't execute the operation. If resolver errors occur, the server can still return partial data.\n\nExample server response with GraphQL error:\n\n```json\n{\n \"errors\": [\n {\n \"message\": \"Cannot query field \\\"nonexistentField\\\" on type \\\"Query\\\".\",\n \"locations\": [{ \"line\": 2, \"column\": 3 }],\n \"extensions\": {\n \"code\": \"GRAPHQL_VALIDATION_FAILED\"\n }\n }\n ],\n \"data\": null\n}\n```\n\nIn Apollo Client 4.x, GraphQL errors are represented by the [`CombinedGraphQLErrors`](https://apollographql.com/docs/react/api/errors/CombinedGraphQLErrors) error type.\n\n### Network Errors\n\nNetwork errors occur when attempting to communicate with your GraphQL server:\n\n- `4xx` or `5xx` HTTP response status codes\n- Network unavailability\n- JSON parsing failures\n- Custom errors from Apollo Link request handlers\n\nNetwork errors might be represented by special error types, but if an api such as the `fetch` API throws a native error (e.g., `TypeError`), Apollo Client will pass it through as-is.\nThrown values that don't fulfill the standard `ErrorLike` interface are wrapped in the [`UnconventionalError`](https://apollographql.com/docs/react/api/errors/UnconventionalError) class, which fulfills the `ErrorLike` interface. As such, you can expect any error returned by Apollo Client to fulfill the `ErrorLike` interface.\n\n```ts\nexport interface ErrorLike {\n message: string;\n name: string;\n stack?: string;\n}\n```\n\n## Error Types\n\nApollo Client 4.x provides specific error classes for different error scenarios:\n\n### CombinedGraphQLErrors\n\nRepresents GraphQL errors returned by the server. Most common error type in applications.\n\n```tsx\nimport { CombinedGraphQLErrors } from \"@apollo/client/errors\";\n\nfunction UserProfile({ userId }: { userId: string }) {\n const { data, error } = useQuery(GET_USER, {\n variables: { id: userId },\n });\n\n // no need to check for nullishness of error, CombinedGraphQLErrors.is handles that\n if (CombinedGraphQLErrors.is(error)) {\n // Handle GraphQL errors\n return (\n \n {error.graphQLErrors.map((err, i) => (\n
\n );\n }\n\n return data ? GraphQL Error: {err.message}
\n ))}\n\n
\n );\n}\n```\n\n### Avoid setting a Global Error Policy\n\nWhile it is possible to set a global error policy using `defaultOptions`, in practice this is discouraged as it can lead to unexpected behavior and type safety issues. The return types of the TypeScript hooks may change depending on the `errorPolicy` passed into the hook, and this can conceptually not take global `defaultOptions` error policies into account. As such, it is best to set the `errorPolicy` per operation as needed.\n\n## Error Links\n\nThe `ErrorLink` can be used to e.g. log error globally or perform specific side effects based on errors happening.\n\nAn `ErrorLink` can't be used to swallow errors fully, but it can be used to retry an operation after handling an error, in which case the error wouldn't propagate. Otherwise, the most common use for `ErrorLink` is logging.\n\n```ts\nimport { ErrorLink } from \"@apollo/client/link/error\";\n\nconst errorLink = new ErrorLink(({ error, operation, forward }) => {\n if (someCondition(error)) {\n // Retry the request, returning the new observable\n return forward(operation);\n }\n\n // Log the error for any unhandled GraphQL errors or network errors.\n console.log(`[Error]: ${error.message}`);\n\n // If nothing is returned from the error handler callback, the error will be\n // emitted from the link chain as normal.\n});\n```\n\n### Retry Link\n\nAlternatively, you can use the `RetryLink` from `@apollo/client/link/retry` to implement retry logic for failed operations.\n\n```typescript\nimport { RetryLink } from \"@apollo/client/link/retry\";\n\nconst retryLink = new RetryLink({\n delay: {\n initial: 300,\n max: Infinity,\n jitter: true,\n },\n attempts: {\n max: 5,\n retryIf: (error, operation) => {\n // Retry on network errors\n return !!error && operation.operationName !== \"SensitiveOperation\";\n },\n },\n});\n\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n link: from([retryLink, errorLink, httpLink]),\n});\n```\n\n### Custom Retry Logic\n\n```typescript\nconst retryLink = new RetryLink({\n attempts: (count, operation, error) => {\n // Don't retry mutations\n if (\n operation.query.definitions.some(\n (def) =>\n def.kind === \"OperationDefinition\" && def.operation === \"mutation\"\n )\n ) {\n return false;\n }\n\n // Retry up to 3 times on network errors\n return count < 3 && !!error;\n },\n delay: (count) => {\n // Exponential backoff\n return Math.min(1000 * Math.pow(2, count), 30000);\n },\n});\n```\n\n## Error Boundaries\n\nWhen using suspenseful hooks, you should use React Error Boundaries for graceful error handling.\n\n### Non-suspense per-Component Error Handling\n\n```tsx\nimport {\n CombinedGraphQLErrors,\n ServerError,\n ServerParseError,\n} from \"@apollo/client/errors\";\n\nfunction SafeUserList() {\n const { data, error, loading, refetch } = useQuery(GET_USERS, {\n errorPolicy: \"all\",\n notifyOnNetworkStatusChange: true,\n });\n\n // Handle network errors\n if (ServerError.is(error) || ServerParseError.is(error)) {\n return (\n Good: {data?.goodField}
\n {error &&Bad: {error.message}}\n \n {CombinedGraphQLErrors.is(error) && (\n \n Some data may be incomplete: {error.graphQLErrors[0].message}\n \n )}\n\n {loading &&
\n );\n}\n```\n","docs/agent-skills/apollo-client/references/fragments.md":"# Fragments Reference\n\nGraphQL fragments define a set of fields for a specific type. In Apollo Client, fragments are especially powerful when colocated with components to define each component's data requirements independently, creating a clear separation of concerns and enabling better component composition.\n\n## Table of Contents\n\n- [What Are Fragments](#what-are-fragments)\n- [Basic Fragment Syntax](#basic-fragment-syntax)\n- [Fragment Colocation](#fragment-colocation)\n- [Fragment Reading Hooks](#fragment-reading-hooks)\n- [Data Masking](#data-masking)\n- [Fragment Registry](#fragment-registry)\n- [TypeScript Integration](#typescript-integration)\n- [Best Practices](#best-practices)\n\n## What Are Fragments\n\nA GraphQL fragment defines a set of fields for a specific GraphQL type. Fragments are defined on a specific GraphQL type and can be included in operations using the spread operator (`...`).\n\nIn Apollo Client, fragments serve a specific purpose:\n\n**Fragments are for colocation, not reuse.** Each component should declare its data needs in a dedicated fragment. This allows components to independently evolve their data requirements without creating artificial dependencies between unrelated parts of your application.\n\nFragments enable:\n\n1. **Component colocation**: Define the exact data requirements for a component alongside the component code\n2. **Independent evolution**: Change a component's data needs without affecting other components\n3. **Code organization**: Compose fragments together to build complete queries that mirror your component hierarchy\n\n## Basic Fragment Syntax\n\n### Defining a Fragment\n\n```typescript\nimport { gql } from \"@apollo/client\";\n\nconst USER_FRAGMENT = gql`\n fragment UserFields on User {\n id\n name\n email\n avatarUrl\n }\n`;\n```\n\nEvery fragment includes:\n\n- A unique name (`UserFields`)\n- The type it operates on (`User`)\n- The fields to select\n\n### Using Fragments in Queries\n\nInclude fragments in queries using the spread operator:\n\n```typescript\nconst GET_USER = gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n ...UserFields\n }\n }\n\n ${USER_FRAGMENT}\n`;\n```\n\nWhen using GraphQL Code Generator with the recommended configuration (typescript, typescript-operations, and typed-document-node plugins), fragments defined in your source files are automatically picked up and generated into typed document nodes. The generated fragment documents already include the fragment definition, so you don't need to interpolate them manually into queries.\n\n## Fragment Colocation\n\nFragment colocation is the practice of defining fragments in the same file as the component that uses them. This creates a clear contract between components and their data requirements.\n\n### Why Colocate Fragments\n\n- **Locality**: Data requirements live next to the code that uses them\n- **Maintainability**: Changes to component UI and data needs happen together\n- **Type safety**: TypeScript can infer exact types from colocated fragments\n- **Independence**: Components can evolve their data requirements without affecting other components\n\n### Colocation Pattern\n\nThe recommended pattern for colocating fragments with components:\n\n```tsx\nimport { gql, FragmentType } from \"@apollo/client\";\nimport { useSuspenseFragment } from \"@apollo/client/react\";\n\n// Fragment definition\n// This will be picked up by Codegen to create `UserCard_UserFragmentDoc` in `./fragments.generated.ts`.\n// As that generated fragment document is correctly typed, we use that in the code going forward.\n// This fragment will never be consumed in runtime code, so it is wrapped in `if (false)` so the bundler can omit it when bundling.\nif (false) {\n gql`\n fragment UserCard_user on User {\n id\n name\n email\n avatarUrl\n }\n `;\n}\n\n// This has been created from above fragment definition by CodeGen and is a correctly typed `TypedDocumentNode`\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated.ts\";\n\n// Component receives the (partially masked) parent object\nexport function UserCard({\n user,\n}: {\n user: FragmentType\n \n
\n );\n}\n```\n\n### Naming Convention\n\nA suggested naming pattern for fragments follows this convention:\n\n```text\n{ComponentName}_{propName}\n```\n\nWhere `propName` is the name of the prop the component receives containing the fragment data.\n\nExamples:\n\n- `UserCard_user` - Fragment for the `user` prop in the UserCard component\n- `PostList_posts` - Fragment for the `posts` prop in the PostList component\n- `CommentItem_comment` - Fragment for the `comment` prop in the CommentItem component\n\nThis convention makes it clear which component owns which fragment. However, you can choose a different naming convention based on your project's needs.\n\n**Note**: A component might accept fragment data through multiple props, in which case it would have multiple associated fragments. For example, a `CommentCard` component might accept both a `comment` prop and an `author` prop, resulting in `CommentCard_comment` and `CommentCard_author` fragments.\n\n### Composing Fragments\n\nParent components compose child fragments to build complete queries:\n\n```tsx\n// Child component\nimport { gql } from \"@apollo/client\";\n\nif (false) {\n gql`\n fragment UserAvatar_user on User {\n id\n avatarUrl\n name\n }\n `;\n}\n\n// Parent component composes child fragments\nif (false) {\n gql`\n fragment UserProfile_user on User {\n id\n name\n email\n bio\n ...UserAvatar_user\n }\n `;\n}\n\n// Page-level query composes all fragments\nif (false) {\n gql`\n query UserProfilePage($id: ID!) {\n user(id: $id) {\n ...UserProfile_user\n }\n }\n `;\n}\n```\n\nThis creates a hierarchy that mirrors your component tree.\n\n## Fragment Reading Hooks\n\nApollo Client provides hooks to read fragment data within components. These hooks work with data masking to ensure components only access the data they explicitly requested.\n\n### useSuspenseFragment\n\nFor components using Suspense and concurrent features:\n\n```tsx\nimport { useSuspenseFragment } from \"@apollo/client/react\";\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.name}
\n{data.email}
\n{data.name}
;\n}\n```\n\n### useFragment\n\nFor components not using Suspense:\n\n```tsx\nimport { useFragment } from \"@apollo/client/react\";\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentTypeLoading...
;\n }\n\n return {data.name}
;\n}\n```\n\nThe `complete` field indicates whether all fragment data is available in the cache.\n\n### Hook Options\n\nBoth hooks accept these options:\n\n```typescript\n{\n // The fragment document (required)\n fragment: TypedDocumentNode,\n\n // The fragment name (optional in most cases)\n // Only required if the fragment document contains multiple definitions\n fragmentName?: string,\n\n // The source data containing the fragment (required)\n // Can be a single object or an array of objects\n from: FragmentType{user.privateData}
;\n}\n```\n\nWith data masking:\n\n```tsx\n// ✅ With data masking - component can only access its fragment data\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.privateData}
;\n\n // Only fields from the fragment are accessible\n return {data.name}
;\n}\n```\n\n### Benefits of Data Masking\n\n- **Prevents over-rendering**: Components only re-render when their specific data changes\n- **Enforces boundaries**: Components can't accidentally depend on data they don't own\n- **Better refactoring**: Safe to modify parent queries without breaking child components\n- **Type safety**: TypeScript catches attempts to access unavailable fields\n\n## Fragment Registry\n\nThe fragment registry is an **alternative approach** to GraphQL Code Generator's automatic fragment inlining by name. It allows you to register fragments globally, making them available throughout your application by name reference.\n\n**Important**: GraphQL Code Generator automatically inlines fragments by name wherever they're used in your queries. Either approach is sufficient on its own—**you don't need to combine them**.\n\n### Creating a Fragment Registry\n\n```typescript\nimport { ApolloClient, InMemoryCache } from \"@apollo/client\";\nimport { createFragmentRegistry } from \"@apollo/client/cache\";\n\nexport const fragmentRegistry = createFragmentRegistry();\n\nconst client = new ApolloClient({\n cache: new InMemoryCache({\n fragments: fragmentRegistry,\n }),\n});\n```\n\n### Registering Fragments\n\nRegister fragments after defining them:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { fragmentRegistry } from \"./apollo/client\";\n\nconst USER_FRAGMENT = gql`\n fragment UserFields on User {\n id\n name\n email\n }\n`;\n\nfragmentRegistry.register(USER_FRAGMENT);\n```\n\nWith colocated fragments:\n\n```tsx\nimport { fragmentRegistry } from \"@/apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\n// Register the fragment globally\nfragmentRegistry.register(UserCard_UserFragmentDoc);\n```\n\n### Using Registered Fragments\n\nOnce registered, fragments can be referenced by name in queries without explicit imports:\n\n```tsx\n// Fragment is available by name because it's registered\nconst GET_USER = gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n ...UserCard_user\n }\n }\n`;\n```\n\n### Approaches for Fragment Composition\n\nThere are three approaches to make child fragments available in parent queries:\n\n1. **GraphQL Code Generator inlining** (Recommended): CodeGen automatically inlines fragments by name. No manual work needed—just reference fragments by name in your queries.\n\n2. **Fragment Registry**: Manually register fragments to make them available by name. Useful for runtime scenarios where CodeGen isn't available.\n\n3. **Manual interpolation**: Explicitly import and interpolate child fragments into parent fragments:\n\n ```typescript\n import { CHILD_FRAGMENT } from \"./ChildComponent\";\n\n const PARENT_FRAGMENT = gql`\n fragment Parent_data on Data {\n field\n ...Child_data\n }\n ${CHILD_FRAGMENT}\n `;\n ```\n\n### Pros and Cons\n\n**GraphQL Code Generator inlining**:\n\n- ✅ Less work: Automatic, no manual registration needed\n- ❌ Larger bundle: Fragments are inlined into every query that uses them\n\n**Fragment Registry**:\n\n- ✅ Smaller bundle: Fragments are registered once, referenced by name\n- ❌ More work: Requires manual registration of each fragment\n- ❌ May cause issues with lazy-loaded modules if the module is not loaded before the query is executed\n- ✅ Best for deeply nested component trees where bundle size matters\n\n**Manual interpolation**:\n\n- ❌ Most work: Manual imports and interpolation required\n- ✅ Explicit: Clear fragment dependencies in code\n\n### Recommendation\n\nFor most applications using GraphQL Code Generator (as shown in this guide), **use the automatic inlining**—it requires no additional setup and works seamlessly. Consider the fragment registry only if bundle size becomes a concern in applications with deeply nested component trees.\n\n## TypeScript Integration\n\nApollo Client provides strong TypeScript support for fragments through GraphQL Code Generator.\n\n### Generated Types\n\nGraphQL Code Generator produces typed fragment documents:\n\n```typescript\n// Generated file: fragments.generated.ts\nexport type UserCard_UserFragment = {\n __typename: \"User\";\n id: string;\n name: string;\n email: string;\n avatarUrl: string;\n} & { \" $fragmentName\"?: \"UserCard_UserFragment\" };\n\nexport const UserCard_UserFragmentDoc: TypedDocumentNode<\n UserCard_UserFragment,\n never\n>;\n```\n\n### Type-Safe Fragment Usage\n\nUse `FragmentType` to accept masked fragment data:\n\n```tsx\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.name}
;\n}\n```\n\n### Fragment Type Inference\n\nTypeScript infers types from fragment documents automatically:\n\n```tsx\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\n// Types are inferred from the fragment\nconst { data } = useSuspenseFragment({\n fragment: UserCard_UserFragmentDoc,\n from: user,\n});\n\n// data.name is string\n// data.email is string\n// data.nonExistentField is a TypeScript error\n```\n\n### Parent-Child Type Safety\n\nWhen passing fragment data from parent to child:\n\n```tsx\n// Parent query\nconst { data } = useSuspenseQuery(GET_USER);\n\n// TypeScript ensures the query includes UserCard_user fragment\n// before allowing it to be passed to UserCard\n{data.name}
;\n}\n```\n\n```tsx\n// ❌ Avoid: Component uses query hook\nfunction UserCard({ userId }: { userId: string }) {\n const { data } = useQuery(GET_USER, { variables: { id: userId } });\n return {data.user.name}
;\n}\n```\n\n### Request Only Required Fields\n\nKeep fragments minimal and only request fields the component actually uses:\n\n```tsx\n// ✅ Good: Only necessary fields\nif (false) {\n gql`\n fragment UserListItem_user on User {\n id\n name\n }\n `;\n}\n```\n\n```tsx\n// ❌ Avoid: Requesting unused fields\nif (false) {\n gql`\n fragment UserListItem_user on User {\n id\n name\n email\n bio\n friends {\n id\n name\n }\n posts {\n id\n title\n }\n }\n `;\n}\n```\n\n### Use @defer for Below-the-Fold Content\n\nThe `@defer` directive allows you to defer loading of non-critical fields, enabling faster initial page loads by prioritizing essential data. The deferred fields are delivered via incremental delivery and arrive after the non-deferred data, allowing the UI to progressively render as data becomes available.\n\nDefer slow fields that aren't immediately visible:\n\n```tsx\nif (false) {\n gql`\n query ProductPage($id: ID!) {\n product(id: $id) {\n id\n name\n price\n ...ProductReviews_product @defer\n }\n }\n `;\n}\n```\n\nThis allows the page to render quickly while reviews load in the background.\n\n### Handle Client-Only Fields\n\nUse the `@client` directive for fields resolved locally:\n\n```tsx\nif (false) {\n gql`\n fragment TodoItem_todo on Todo {\n id\n text\n completed\n isSelected @client\n }\n `;\n}\n```\n\n### Enable Data Masking for New Applications\n\nAlways enable data masking in new applications:\n\n```typescript\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n dataMasking: true,\n});\n```\n\nThis enforces proper boundaries from the start and prevents accidental coupling between components.\n\n## Apollo Client Data Masking vs GraphQL-Codegen Fragment Masking\n\nApollo Client's data masking and GraphQL Code Generator's fragment masking are different features that serve different purposes:\n\n### GraphQL-Codegen Fragment Masking\n\nGraphQL Code Generator's fragment masking (when using the client preset) is a **type-level** feature:\n\n- Masks data only at the TypeScript type level\n- The actual runtime data remains fully accessible on the object\n- Using their `useFragment` hook simply \"unmasks\" the data on a type level\n- Does not prevent accidental access to data at runtime\n- Parent components receive all data and pass it down\n- This means the parent component has to be subscribed to all data\n\n### Apollo Client Data Masking\n\nApollo Client's data masking is a **runtime** feature with significant performance benefits:\n\n- Removes data at the runtime level, not just the type level\n- The `useFragment` and `useSuspenseFragment` hooks create cache subscriptions\n- Parent objects are sparse and only contain unmasked data\n- Prevents accidental access to data that should be masked\n\n### Key Benefits of Apollo Client Data Masking\n\n**1. No Accidental Data Access**\n\nWith runtime data masking, masked fields are not present in the parent object at all. You cannot accidentally access them, even if you bypass TypeScript type checking.\n\n**2. Fewer Re-renders**\n\nApollo Client's approach creates more efficient subscriptions:\n\n- **Without data masking**: Parent component subscribes to all fields (including masked ones). When a masked child field changes, the parent re-renders to pass that runtime data down the tree.\n- **With data masking**: Parent component only subscribes to its own unmasked fields. Subscriptions on masked fields happen lower in the React component tree when the child component calls `useSuspenseFragment`. When a masked field changes, only the child component that subscribed to it re-renders.\n\n### Example\n\n```tsx\nimport { FragmentType } from \"@apollo/client\";\nimport { useSuspenseQuery, useSuspenseFragment } from \"@apollo/client/react\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction ParentComponent() {\n const { data } = useSuspenseQuery(GET_USER);\n\n // With Apollo Client data masking:\n // - data.user only contains unmasked fields\n // - Parent doesn't re-render when child-specific fields change\n\n return {data.name}
;\n}\n```\n\nThis granular subscription approach improves performance in large applications with deeply nested component trees.\n","docs/agent-skills/apollo-client/references/integration-client.md":"# Apollo Client Integration for Client-Side Apps\n\nThis guide covers setting up Apollo Client in client-side React applications without server-side rendering (SSR). This includes applications using Vite, Parcel, Create React App, or other bundlers that don't implement SSR.\n\nFor applications with SSR, use one of the framework-specific integration guides instead:\n\n- [Next.js App Router](integration-nextjs.md)\n- [React Router Framework Mode](integration-react-router.md)\n- [TanStack Start](integration-tanstack-start.md)\n\n## Installation\n\n```bash\nnpm install @apollo/client graphql rxjs\n```\n\n## TypeScript Code Generation (optional but recommended)\n\nFor type-safe GraphQL operations with TypeScript, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\n## Setup Steps\n\n### Step 1: Create Client\n\n```typescript\nimport { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\";\n\n// Recommended: Use HttpOnly cookies for authentication\nconst httpLink = new HttpLink({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n credentials: \"include\", // Sends cookies with requests (secure when using HttpOnly cookies)\n});\n\nconst client = new ApolloClient({\n link: httpLink,\n cache: new InMemoryCache(),\n});\n```\n\nIf you need manual token management (less secure, only when HttpOnly cookies aren't available):\n\n```typescript\nimport { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\";\nimport { SetContextLink } from \"@apollo/client/link/context\";\n\nconst httpLink = new HttpLink({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n});\n\nconst authLink = new SetContextLink(({ headers }) => {\n const token = localStorage.getItem(\"token\");\n return {\n headers: {\n ...headers,\n authorization: token ? `Bearer ${token}` : \"\",\n },\n };\n});\n\nconst client = new ApolloClient({\n link: authLink.concat(httpLink),\n cache: new InMemoryCache(),\n});\n```\n\n### Step 2: Setup Provider\n\n```tsx\nimport { ApolloProvider } from \"@apollo/client\";\nimport App from \"./App\";\n\nfunction Root() {\n return (\n Loading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return (\n- {data?.users.map((user) =>
- {user.name} )}
Loading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return{data?.user.name}
;\n}\n```\n\n> **Note for TypeScript users**: Use [`dataState`](https://www.apollographql.com/docs/react/data/typescript#type-narrowing-data-with-datastate) for more robust type safety and better type narrowing in Apollo Client 4.x.\n\n### TypeScript Integration\n\nFor complete examples with loading, error handling, and `dataState` for type narrowing, see [Basic Query Usage](#basic-query-usage) above.\n\n#### Usage with Generated Types\n\nFor type-safe operations with code generation, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\nQuick example:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useQuery } from \"@apollo/client/react\";\nimport { GetUserDocument } from \"./queries.generated\";\n\n// Define your query with the if (false) pattern for code generation\nif (false) {\n gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n id\n name\n email\n }\n }\n `;\n}\n\nfunction UserProfile({ userId }: { userId: string }) {\n // Types are automatically inferred from GetUserDocument\n const { data } = useQuery(GetUserDocument, {\n variables: { id: userId },\n });\n\n return {data.user.name}
;\n}\n```\n\n#### Usage with Manual Type Annotations\n\nIf not using code generation, define types alongside your queries using `TypedDocumentNode`:\n\n```typescript\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\nimport { useQuery } from \"@apollo/client/react\";\n\ninterface GetUserData {\n user: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface GetUserVariables {\n id: string;\n}\n\n// Types should always be defined via TypedDocumentNode alongside your queries/mutations, not at the useQuery/useMutation call site\nconst GET_USER: TypedDocumentNode{data.user.name}
;\n}\n```\n\n## Basic Mutation Usage\n\n```tsx\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\nimport { useMutation } from \"@apollo/client/react\";\n\ninterface CreateUserMutation {\n createUser: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface CreateUserMutationVariables {\n input: {\n name: string;\n email: string;\n };\n}\n\nconst CREATE_USER: TypedDocumentNode<\n CreateUserMutation,\n CreateUserMutationVariables\n> = gql`\n mutation CreateUser($input: CreateUserInput!) {\n createUser(input: $input) {\n id\n name\n email\n }\n }\n`;\n\nfunction CreateUserForm() {\n const [createUser, { loading, error }] = useMutation(CREATE_USER);\n\n const handleSubmit = async (formData: FormData) => {\n const { data } = await createUser({\n variables: {\n input: {\n name: formData.get(\"name\") as string,\n email: formData.get(\"email\") as string,\n },\n },\n });\n if (data) {\n console.log(\"Created user:\", data.createUser);\n }\n };\n\n return (\n Error: {error.message}
}\n \n );\n}\n```\n\n## Client Configuration Options\n\n```typescript\nconst client = new ApolloClient({\n // Required: The cache implementation\n cache: new InMemoryCache({\n typePolicies: {\n Query: {\n fields: {\n // Field-level cache configuration\n },\n },\n },\n }),\n\n // Network layer\n link: new HttpLink({ uri: \"/graphql\" }),\n\n // Avoid defaultOptions if possible as they break TypeScript expectations.\n // Configure options per-query/mutation instead for better type safety.\n // defaultOptions: {\n // watchQuery: { fetchPolicy: 'cache-and-network' },\n // },\n\n // DevTools are enabled by default in development\n // Only configure when enabling in production\n devtools: {\n enabled: true, // Only needed for production\n },\n\n // Custom name for this client instance\n clientAwareness: {\n name: \"web-client\",\n version: \"1.0.0\",\n },\n});\n```\n\n## Important Considerations\n\n1. **Choose Your Hook Strategy:** Decide if your application should be based on Suspense. If it is, use suspenseful hooks like `useSuspenseQuery` (see [Suspense Hooks guide](suspense-hooks.md)), otherwise use non-suspenseful hooks like `useQuery` (see [Queries guide](queries.md)).\n\n2. **Client-Side Only:** This setup is for client-side apps without SSR. The Apollo Client instance is created once and reused throughout the application lifecycle.\n\n3. **Authentication:** Prefer HttpOnly cookies with `credentials: \"include\"` in `HttpLink` options to avoid exposing tokens to JavaScript. If manual token management is necessary, use `SetContextLink` to dynamically add authentication headers from `localStorage` or other client-side storage.\n\n4. **Environment Variables:** Store your GraphQL endpoint URL in environment variables for different environments (development, staging, production).\n\n5. **Error Handling:** Always handle `loading` and `error` states when using `useQuery` or `useLazyQuery`. For Suspense-based hooks (`useSuspenseQuery`), React handles this through `{data.user.name}
;\n}\n```\n\n### Override Next.js Fetch Options\n\nYou can override Next.js-specific `fetch` options per query using `context.fetchOptions`:\n\n```typescript\nconst { data } = await getClient().query({\n query: GET_USER,\n context: {\n fetchOptions: {\n next: { revalidate: 60 }, // Revalidate every 60 seconds\n },\n },\n});\n```\n\n## Setup for Client Components (SSR and Browser)\n\n### Step 1: Create Apollo Wrapper Component\n\nCreate `app/ApolloWrapper.tsx`:\n\n```typescript\n\"use client\";\n\nimport { HttpLink } from \"@apollo/client\";\nimport {\n ApolloNextAppProvider,\n ApolloClient,\n InMemoryCache,\n} from \"@apollo/client-integration-nextjs\";\n\nfunction makeClient() {\n const httpLink = new HttpLink({\n // Use an absolute URL for SSR\n uri: \"https://your-api.com/graphql\",\n fetchOptions: {\n // Optional: Next.js-specific fetch options\n // Note: This doesn't work with `export const dynamic = \"force-static\"`\n },\n });\n\n return new ApolloClient({\n cache: new InMemoryCache(),\n link: httpLink,\n });\n}\n\nexport function ApolloWrapper({ children }: React.PropsWithChildren) {\n return (\n {data.user.name}
;\n}\n```\n\n## Preloading Data from RSC to Client Components\n\nYou can preload data in React Server Components to populate the cache of your Client Components.\n\n### Step 1: Use PreloadQuery in Server Components\n\n```tsx\nimport { PreloadQuery } from \"./ApolloClient\";\nimport { Suspense } from \"react\";\n\nexport default async function Page() {\n return (\n {data.user.name}
;\n}\n```\n\n> **Important:** Data fetched this way should be considered client data and never referenced in Server Components. `PreloadQuery` prevents mixing server data and client data by creating a separate `ApolloClient` instance.\n\n### Using with useReadQuery\n\nFor advanced use cases, you can use `PreloadQuery` with `useReadQuery` to avoid request waterfalls:\n\n```tsx\n{data.user.name}
;\n}\n```\n\n## Handling Multipart Responses (@defer) in SSR\n\nWhen using the `@defer` directive, `useSuspenseQuery` will only suspend until the initial response is received. To handle deferred data properly, you have three strategies:\n\n### Strategy 1: Use PreloadQuery with useReadQuery\n\n`PreloadQuery` allows deferred data to be fully transported and streamed chunk-by-chunk.\n\n### Strategy 2: Remove @defer Fragments\n\nUse `RemoveMultipartDirectivesLink` to strip `@defer` directives from queries during SSR:\n\n```typescript\nimport { RemoveMultipartDirectivesLink } from \"@apollo/client-integration-nextjs\";\n\nnew RemoveMultipartDirectivesLink({\n stripDefer: true, // Default: true\n});\n```\n\nYou can exclude specific fragments from stripping by labeling them:\n\n```graphql\nquery myQuery {\n fastField\n ... @defer(label: \"SsrDontStrip1\") {\n slowField1\n }\n}\n```\n\n### Strategy 3: Wait for Deferred Data\n\nUse `AccumulateMultipartResponsesLink` to debounce the initial response:\n\n```typescript\nimport { AccumulateMultipartResponsesLink } from \"@apollo/client-integration-nextjs\";\n\nnew AccumulateMultipartResponsesLink({\n cutoffDelay: 100, // Wait up to 100ms for incremental data\n});\n```\n\n### Combined Approach: SSRMultipartLink\n\nCombine both strategies with `SSRMultipartLink`:\n\n```typescript\nimport { SSRMultipartLink } from \"@apollo/client-integration-nextjs\";\n\nnew SSRMultipartLink({\n stripDefer: true,\n cutoffDelay: 100,\n});\n```\n\n## Testing\n\nReset singleton instances between tests using the `resetApolloClientSingletons` helper:\n\n```typescript\nimport { resetApolloClientSingletons } from \"@apollo/client-integration-nextjs\";\n\nafterEach(resetApolloClientSingletons);\n```\n\n## Debugging\n\nEnable verbose logging in your `app/ApolloWrapper.tsx`:\n\n```typescript\nimport { setLogVerbosity } from \"@apollo/client\";\n\nsetLogVerbosity(\"debug\");\n```\n\n## Important Considerations\n\n1. **Separate RSC and SSR Queries:** Avoid overlapping queries between RSC and SSR. RSC queries don't update in the browser, while SSR queries can update dynamically as the cache changes.\n\n2. **Use Absolute URLs:** Always use absolute URLs in `HttpLink` for SSR, as relative URLs cannot be used in server-side rendering.\n\n3. **Streaming SSR:** For optimal performance, use `useSuspenseQuery` and `useFragment` to take advantage of React 18's streaming SSR capabilities.\n\n4. **Suspense Boundaries:** Place `Suspense` boundaries at meaningful places in your UI for the best user experience.\n","docs/agent-skills/apollo-client/references/integration-react-router.md":"# Apollo Client Integration with React Router Framework Mode\n\nThis guide covers integrating Apollo Client in a React Router 7 application with support for modern streaming SSR.\n\n## Installation\n\nInstall Apollo Client and the React Router integration package:\n\n```bash\nnpm install @apollo/client-integration-react-router @apollo/client graphql rxjs\n```\n\n> **TypeScript users:** For type-safe GraphQL operations, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\n## Setup\n\n### Step 1: Create Apollo Configuration\n\nCreate an `app/apollo.ts` file that exports a `makeClient` function and an `apolloLoader`:\n\n```typescript\nimport { HttpLink, InMemoryCache } from \"@apollo/client\";\nimport {\n createApolloLoaderHandler,\n ApolloClient,\n} from \"@apollo/client-integration-react-router\";\n\n// `request` will be available on the server during SSR or in loaders, but not in the browser\nexport const makeClient = (request?: Request) => {\n return new ApolloClient({\n cache: new InMemoryCache(),\n link: new HttpLink({ uri: \"https://your-graphql-endpoint.com/graphql\" }),\n });\n};\n\nexport const apolloLoader = createApolloLoaderHandler(makeClient);\n```\n\n> **Important:** `ApolloClient` must be imported from `@apollo/client-integration-react-router`, not from `@apollo/client`.\n\n### Step 2: Reveal Entry Files\n\nRun the following command to create the entry files if they don't exist:\n\n```bash\nnpx react-router reveal\n```\n\nThis will create `app/entry.client.tsx` and `app/entry.server.tsx`.\n\n### Step 3: Configure Client Entry\n\nAdjust `app/entry.client.tsx` to wrap your app in `ApolloProvider`:\n\n```typescript\nimport { makeClient } from \"./apollo\";\nimport { ApolloProvider } from \"@apollo/client\";\nimport { StrictMode, startTransition } from \"react\";\nimport { hydrateRoot } from \"react-dom/client\";\nimport { HydratedRouter } from \"react-router/dom\";\n\nstartTransition(() => {\n const client = makeClient();\n hydrateRoot(\n document,\n \n
\n );\n}\n```\n\n> **Important:** To provide better TypeScript support, `apolloLoader` is a method that you need to call twice: `apolloLoader{data.user.name}
\n{data.user.email}
\n\n
\n );\n}\n```\n\n## Important Considerations\n\n1. **Import ApolloClient from Integration Package:** Always import `ApolloClient` from `@apollo/client-integration-react-router`, not from `@apollo/client`, to ensure proper SSR hydration.\n\n2. **TypeScript Support:** The `apolloLoader` function requires double invocation for proper TypeScript type inference: `apolloLoader{userData.user.name}
\nPosts
\n- \n {postsData.posts.map((post) => (\n
- {post.title} \n ))}\n
\n
\n );\n}\n```\n\n### Option 2: Direct useSuspenseQuery in Component\n\nYou can also use Apollo Client's suspenseful hooks directly in your component without a loader:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\nimport { createFileRoute } from \"@tanstack/react-router\";\nimport type { TypedDocumentNode } from \"@apollo/client\";\n\n// TypedDocumentNode definition with types\nconst GET_POSTS: TypedDocumentNode<{\n posts: Array<{ id: string; title: string; content: string }>;\n}> = gql`\n query GetPosts {\n posts {\n id\n title\n content\n }\n }\n`;\n\nexport const Route = createFileRoute(\"/posts\")({\n component: RouteComponent,\n});\n\nfunction RouteComponent() {\n const { data } = useSuspenseQuery(GET_POSTS);\n\n return (\n {data.user.name}
\n{data.user.email}
\n\n
\n );\n}\n```\n\n### Multiple Queries in a Loader\n\nYou can preload multiple queries in a single loader:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useReadQuery } from \"@apollo/client/react\";\nimport { createFileRoute } from \"@tanstack/react-router\";\n\n// TypedDocumentNode definitions omitted for brevity\n\nexport const Route = createFileRoute(\"/dashboard\")({\n component: RouteComponent,\n loader: ({ context: { preloadQuery } }) => {\n const userQueryRef = preloadQuery(GET_USER, {\n variables: { id: \"current\" },\n });\n\n const statsQueryRef = preloadQuery(GET_STATS, {\n variables: { period: \"month\" },\n });\n\n return {\n userQueryRef,\n statsQueryRef,\n };\n },\n});\n\nfunction RouteComponent() {\n const { userQueryRef, statsQueryRef } = Route.useLoaderData();\n const { data: userData } = useReadQuery(userQueryRef);\n const { data: statsData } = useReadQuery(statsQueryRef);\n\n return (\n Posts
\n- \n {data.posts.map((post) => (\n
- \n
{post.title}
\n{post.content}
\n \n ))}\n
\n
\n );\n}\n```\n\n### Using useQueryRefHandlers for Refetching\n\nWhen using `useReadQuery`, you can get refetch functionality from `useQueryRefHandlers`:\n\n> **Important:** Always call `useQueryRefHandlers` before `useReadQuery`. These two hooks interact with the same `queryRef`, and calling them in the wrong order could cause subtle bugs.\n\n```typescript\nimport { useReadQuery, useQueryRefHandlers, QueryRef } from \"@apollo/client/react\";\n\nfunction UserComponent({ queryRef }: { queryRef: QueryRefWelcome, {userData.user.name}
\n\n
\n Monthly Stats
\nViews: {statsData.stats.views}
\nClicks: {statsData.stats.clicks}
\n\n
\n );\n}\n```\n\n## Important Considerations\n\n1. **Import from Integration Package:** Always import `ApolloClient` and `InMemoryCache` from `@apollo/client-integration-tanstack-start`, not from `@apollo/client`, to ensure proper SSR hydration.\n\n2. **Context Type:** Use `createRootRouteWithContext{data.user.name}
\n \nError: {error.message}
}\n \n );\n}\n```\n\n### Return Tuple\n\n```typescript\nconst [\n mutateFunction, // Function to call to execute mutation\n {\n data, // Mutation result data\n loading, // True while mutation is in flight\n error, // ApolloError if mutation failed\n called, // True if mutation has been called\n reset, // Reset mutation state\n client, // Apollo Client instance\n },\n] = useMutation(MUTATION);\n```\n\n## Mutation Variables\n\n### Variables in Options\n\n```tsx\nconst [createUser] = useMutation(CREATE_USER, {\n variables: {\n input: {\n name: \"Default User\",\n email: \"default@example.com\",\n },\n },\n});\n\n// Call with default variables\nawait createUser();\n\n// Override variables\nawait createUser({\n variables: {\n input: {\n name: \"Custom User\",\n email: \"custom@example.com\",\n },\n },\n});\n```\n\n### TypeScript Types\n\nUse `TypedDocumentNode` instead of generic type parameters:\n\n```typescript\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\n\ninterface CreateUserData {\n createUser: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface CreateUserVariables {\n input: {\n name: string;\n email: string;\n };\n}\n\nconst CREATE_USER: TypedDocumentNode\n
\n );\n }\n\n return (\n \n );\n}\n```\n\n### Async/Await Pattern\n\nIf you only need the promise without using the hook's loading/data state, use `client.mutate` instead:\n\n```tsx\nimport { useApolloClient } from \"@apollo/client/react\";\n\nfunction CreatePost() {\n const client = useApolloClient();\n\n async function handleSubmit(formData: FormData) {\n try {\n const { data } = await client.mutate({\n mutation: CREATE_POST,\n variables: {\n input: {\n title: formData.get(\"title\"),\n content: formData.get(\"content\"),\n },\n },\n });\n console.log(\"Created:\", data.createPost);\n router.push(`/posts/${data.createPost.id}`);\n } catch (error) {\n console.error(\"Failed to create post:\", error);\n }\n }\n\n return (\n Post created: {data.createPost.title}
\n \nLoading...
;\n if (error) returnError: {error.message}
;\n\n return- {data?.dogs.map((dog) =>
- {dog.breed} )}
Error: {error.message}
;\n\n return\n {loading &&
\n );\n}\n```\n\n### Network Status\n\n```tsx\nimport { NetworkStatus } from \"@apollo/client\";\n\nfunction Dogs() {\n const { loading, error, data, networkStatus, refetch } = useQuery(GET_DOGS, {\n notifyOnNetworkStatusChange: true,\n });\n\n if (networkStatus === NetworkStatus.refetch) {\n return Refetching...
;\n }\n\n if (loading) returnLoading...
;\n if (error) returnError: {error.message}
;\n\n return (\n <>\n \n- \n {data.dogs.map((dog) => (\n
- {dog.breed} \n ))}\n
Loading...
;\n if (error) returnError: {error.message}
;\n\n return (\n\n {data?.dog && }\n \n
\n );\n}\n```\n\n### When to Use client.query Instead\n\nIf you only need the promise result and don't consume the loading/error/data states from the hook, use `client.query` instead:\n\n```tsx\nimport { useApolloClient } from \"@apollo/client/react\";\n\nfunction SearchDogs() {\n const client = useApolloClient();\n const [search, setSearch] = useState(\"\");\n\n const handleSearch = async () => {\n try {\n const { data } = await client.query({\n query: SEARCH_DOGS,\n variables: { query: search },\n });\n console.log(\"Found dogs:\", data.searchDogs);\n } catch (error) {\n console.error(\"Search failed:\", error);\n }\n };\n\n return (\n \n setSearch(e.target.value)} />\n \n
\n );\n}\n```\n\n## Polling and Refetching\n\n### Polling\n\n```tsx\nfunction LiveFeed() {\n const { data, startPolling, stopPolling } = useQuery(GET_FEED, {\n pollInterval: 5000, // Poll every 5 seconds\n });\n\n // Or control polling dynamically\n useEffect(() => {\n startPolling(5000);\n return () => stopPolling();\n }, [startPolling, stopPolling]);\n\n return \n \n \n
\n );\n}\n```\n\n## Fetch Policies\n\nControl how the query interacts with the cache.\n\n| Policy | Description |\n| ------------------- | ---------------------------------------------------------- |\n| `cache-first` | Return cached data if available, otherwise fetch (default) |\n| `cache-only` | Only return cached data, never fetch |\n| `cache-and-network` | Return cached data immediately, then fetch and update |\n| `network-only` | Always fetch, update cache, ignore cached data |\n| `no-cache` | Always fetch, never read or write cache |\n| `standby` | Same as cache-first but doesn't auto-update |\n\n### Usage Examples\n\n```tsx\n// Real-time data - always fetch\nconst { data } = useQuery(GET_NOTIFICATIONS, {\n fetchPolicy: \"network-only\",\n});\n\n// Static data - prefer cache\nconst { data } = useQuery(GET_CATEGORIES, {\n fetchPolicy: \"cache-first\",\n});\n\n// Show cached data while fetching fresh data\nconst { data, loading } = useQuery(GET_POSTS, {\n fetchPolicy: \"cache-and-network\",\n});\n\n// Fetch once, then use cache\nconst { data } = useQuery(GET_USER_PROFILE, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: \"cache-first\",\n});\n```\n\n### nextFetchPolicy\n\n```tsx\n// First request: network-only\n// Subsequent requests: cache-first\nconst { data } = useQuery(GET_POSTS, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: \"cache-first\",\n});\n\n// Or use a function for more control\nconst { data } = useQuery(GET_POSTS, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: (currentFetchPolicy, { reason, observable }) => {\n if (reason === \"after-fetch\") {\n return \"cache-first\";\n }\n return currentFetchPolicy;\n },\n});\n```\n\n## Conditional Queries\n\n### Using skipToken (Recommended)\n\nUse `skipToken` to conditionally skip queries without TypeScript issues:\n\n```tsx\nimport { skipToken } from \"@apollo/client\";\n\nfunction UserProfile({ userId }: { userId: string | null }) {\n const { data } = useQuery(\n GET_USER,\n !userId ? skipToken : (\n {\n variables: { id: userId },\n }\n )\n );\n\n return userId ? - {data?.dogs.map((dog) =>
- {dog.breed} )}
Select a user
;\n}\n```\n\n### Skip Option (Alternative)\n\n```tsx\nfunction UserProfile({ userId }: { userId: string | null }) {\n const { data } = useQuery(GET_USER, {\n variables: { id: userId! },\n skip: !userId, // Don't execute if no userId\n });\n\n return userId ?Select a user
;\n}\n```\n\n> **Note**: Using `skipToken` is preferred over `skip` as it avoids TypeScript issues with required variables and the non-null assertion operator.\n\n### SSR Skip\n\n```tsx\n// Skip during server-side rendering\nconst { data } = useQuery(GET_USER_LOCATION, {\n skip: typeof window === \"undefined\",\n ssr: false,\n});\n```\n","docs/agent-skills/apollo-client/references/state-management.md":"# State Management Reference\n\n## Table of Contents\n\n- [Reactive Variables](#reactive-variables)\n- [Local-Only Fields](#local-only-fields)\n- [LocalState Resolvers](#localstate-resolvers)\n- [Combining Remote and Local State](#combining-remote-and-local-state)\n- [useReactiveVar Hook](#usereactivevar-hook)\n\n## Reactive Variables\n\nReactive variables are a way to store local state outside of the Apollo Client cache while still triggering reactive updates.\n\n**Important**: Reactive variables store a single value that notifies `ApolloClient` instances when changed. They do not have separate values per ApolloClient instance. In multi-user environments like SSR, global or module-level reactive variables could be shared between users and cause data leaks. In frameworks that use SSR, always avoid storing reactive variables as globals.\n\n### Creating Reactive Variables\n\n```typescript\nimport { makeVar } from \"@apollo/client\";\n\n// Simple reactive variable\nexport const isLoggedInVar = makeVar\n
\n );\n}\n```\n\n### Local Field Read Functions (Type Policies)\n\nLocal field `read` functions are defined in entity-level type policies. You can use reactive variables inside these `read` functions, along with other calculations or derived values:\n\n```typescript\nconst cache = new InMemoryCache({\n typePolicies: {\n User: {\n fields: {\n // Simple local field from reactive variable\n isSelected: {\n read(_, { readField }) {\n const id = readField(\"id\");\n return selectedUsersVar().includes(id);\n },\n },\n\n // Computed local field (derived value)\n displayName: {\n read(_, { readField }) {\n const name = readField(\"name\");\n const email = readField(\"email\");\n return name || email?.split(\"@\")[0] || \"Anonymous\";\n },\n },\n },\n },\n },\n});\n```\n\n## LocalState Resolvers\n\n### Query-Level Local Resolvers\n\nQuery-level local fields can be defined using `LocalState` resolvers. **Note**: Do not read reactive variables inside LocalState resolvers - this is not a documented/tested feature. It might not behave as expected.\n\n```typescript\nimport { LocalState } from \"@apollo/client/local-state\";\n\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n localState: new LocalState({\n resolvers: {\n Query: {\n // Read from localStorage\n theme: () => {\n if (typeof window !== \"undefined\") {\n return localStorage.getItem(\"theme\") || \"light\";\n }\n return \"light\";\n },\n\n // Read from cache\n currentUser: (_, __, { cache }) => {\n if (typeof window === \"undefined\") return null;\n const userId = localStorage.getItem(\"currentUserId\");\n if (!userId) return null;\n return cache.readFragment({\n id: cache.identify({ __typename: \"User\", id: userId }),\n fragment: gql`\n fragment CurrentUser on User {\n id\n name\n email\n }\n `,\n });\n },\n\n // Compute value\n isOnline: () => {\n if (typeof navigator !== \"undefined\") {\n return navigator.onLine;\n }\n return true;\n },\n },\n },\n }),\n});\n```\n\n### Using Local Query Fields\n\n```tsx\nconst GET_AUTH_STATE = gql`\n query GetAuthState {\n isLoggedIn @client\n currentUser @client {\n id\n name\n email\n }\n }\n`;\n\nfunction AuthStatus() {\n const { data } = useQuery(GET_AUTH_STATE);\n\n if (!data?.isLoggedIn) {\n return {data?.user.displayName}
\n{data?.user.email}
\n\n
\n );\n}\n```\n\n### Multiple Reactive Variables\n\n```tsx\nfunction AppLayout() {\n const theme = useReactiveVar(themeVar);\n const sidebarOpen = useReactiveVar(sidebarOpenVar);\n const isLoggedIn = useReactiveVar(isLoggedInVar);\n\n return (\n Items: {totalItems}
\nTotal: ${totalPrice.toFixed(2)}
\n\n {isLoggedIn && sidebarOpen && \n \n
\n );\n}\n```\n","docs/agent-skills/apollo-client/references/suspense-hooks.md":"# Suspense Hooks Reference\n\n> **Note**: Suspense hooks are the recommended approach for data fetching in modern React applications (React 18+). They provide cleaner code, better loading state handling, and enable streaming SSR.\n\n## Table of Contents\n\n- [useSuspenseQuery Hook](#usesuspensequery-hook)\n- [useBackgroundQuery and useReadQuery](#usebackgroundquery-and-usereadquery)\n- [useLoadableQuery](#useloadablequery)\n- [createQueryPreloader](#createquerypreloader)\n- [useQueryRefHandlers](#usequeryrefhandlers)\n- [Distinguishing Queries with queryKey](#distinguishing-queries-with-querykey)\n- [Suspense Boundaries and Error Handling](#suspense-boundaries-and-error-handling)\n- [Transitions](#transitions)\n- [Avoiding Request Waterfalls](#avoiding-request-waterfalls)\n- [Fetch Policies](#fetch-policies)\n- [Streaming SSR or React Server Components](#streaming-ssr-or-react-server-components)\n- [Conditional Queries](#conditional-queries)\n\n## useSuspenseQuery Hook\n\nThe `useSuspenseQuery` hook is the Suspense-ready replacement for `useQuery`. It initiates a network request and causes the component calling it to suspend while the request is made. Unlike `useQuery`, it does not return `loading` states—these are handled by React's Suspense boundaries and error boundaries.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\nimport { GET_DOG } from \"./queries.generated\";\n\nfunction App() {\n return (\n Name: {data.dog.name}
;\n}\n```\n\n### Return Object\n\n```typescript\nconst {\n data, // Query result data\n dataState, // With default options: \"complete\" | \"streaming\"\n // With returnPartialData: also \"partial\"\n // With errorPolicy \"all\" or \"ignore\": also \"empty\"\n error, // ApolloError (only when errorPolicy is \"all\" or \"ignore\")\n networkStatus, // NetworkStatus.ready, NetworkStatus.loading, etc.\n client, // Apollo Client instance\n refetch, // Function to re-execute query\n fetchMore, // Function for pagination\n} = useSuspenseQuery(QUERY, options);\n```\n\n### Key Differences from useQuery\n\n- **No `loading` boolean**: Component suspends instead of returning `loading: true`\n- **Error handling**: With default `errorPolicy` (`none`), errors are thrown and caught by error boundaries. With `errorPolicy: \"all\"` or `\"ignore\"`, the `error` property is returned and `data` may be `undefined`.\n- **`data` availability**: With default `errorPolicy` (`none`), `data` is guaranteed to be present when the component renders. With `errorPolicy: \"all\"` or `\"ignore\"`, when `dataState` is `empty`, `data` may be `undefined`.\n- **Suspense boundaries**: Must wrap component with `Name: {data.dog.name}
\n Breed: {data.dog.breed}
\n \n );\n}\n```\n\n### Rendering Partial Data\n\nUse `returnPartialData` to render immediately with partial cache data instead of suspending. The component will still suspend if there is no data in the cache.\n\n```tsx\nfunction Dog({ id }: { id: string }) {\n const { data } = useSuspenseQuery(GET_DOG, {\n variables: { id },\n returnPartialData: true,\n });\n\n return (\n <>\n Name: {data.dog?.name ?? \"Unknown\"}
\n {data.dog?.breed && Breed: {data.dog.breed}
}\n \n );\n}\n```\n\n## useBackgroundQuery and useReadQuery\n\nUse `useBackgroundQuery` with `useReadQuery` to avoid request waterfalls by starting a query in a parent component and reading the result in a child component. This pattern enables the parent to start fetching data before the child component renders.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useBackgroundQuery, useReadQuery } from \"@apollo/client/react\";\n\nfunction Parent() {\n // Start fetching immediately\n const [queryRef] = useBackgroundQuery(GET_DOG, {\n variables: { id: \"3\" },\n });\n\n return (\n Name: {data.dog.name}
;\n}\n```\n\n### When to Use\n\n- **Avoiding waterfalls**: Start fetching data in a parent (preferably above a suspense boundary) before child components render\n- **Preloading data**: Begin fetching before the component that needs the data is ready\n- **Parallel queries**: Start multiple queries at once in a parent component\n\n### Return Values\n\n`useBackgroundQuery` returns a tuple:\n\n```typescript\nconst [\n queryRef, // QueryRef to pass to useReadQuery\n { refetch, fetchMore, subscribeToMore }, // Helper functions\n] = useBackgroundQuery(QUERY, options);\n```\n\n`useReadQuery` returns the query result:\n\n```typescript\nconst {\n data, // Query result data (always defined)\n dataState, // \"complete\" | \"streaming\" | \"partial\" | \"empty\"\n error, // ApolloError (if errorPolicy allows)\n networkStatus, // Detailed network state (1-8)\n} = useReadQuery(queryRef);\n```\n\n## useLoadableQuery\n\nUse `useLoadableQuery` to imperatively load a query in response to a user interaction (like a button click) instead of on component mount.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useLoadableQuery, useReadQuery } from \"@apollo/client/react\";\nimport { GET_GREETING } from \"./queries.generated\";\n\nfunction App() {\n const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);\n\n return (\n <>\n {data.greeting.message}
;\n}\n```\n\n### Return Values\n\n```typescript\nconst [\n loadQuery, // Function to load the query\n queryRef, // QueryRef (null until loadQuery is called)\n { refetch, fetchMore, subscribeToMore, reset }, // Helper functions\n] = useLoadableQuery(QUERY, options);\n```\n\n### When to Use\n\n- **User-triggered fetching**: Load data in response to user actions\n- **Lazy loading**: Defer data fetching until it's actually needed\n- **Progressive disclosure**: Load data for UI elements that may not be initially visible\n\n## createQueryPreloader\n\nThe `createQueryPreloader` function creates a `preloadQuery` function that can be used to initiate queries outside of React components. This is useful for preloading data before a component renders, such as in route loaders or event handlers.\n\n### Basic Usage\n\n```tsx\nimport { ApolloClient, InMemoryCache } from \"@apollo/client\";\nimport { createQueryPreloader } from \"@apollo/client/react\";\n\nconst client = new ApolloClient({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n cache: new InMemoryCache(),\n});\n\n// Create a preload function\nexport const preloadQuery = createQueryPreloader(client);\n```\n\n### Using preloadQuery with Route Loaders\n\n> **Note**: This example applies to React Router in non-framework mode. For React Router framework mode, see [integration-react-router.md](./integration-react-router.md).\n\nUse the preload function with React Router's `loader` function to begin loading data during route transitions:\n\n```tsx\nimport { preloadQuery } from \"@/lib/apollo-client\";\nimport { GET_DOG } from \"./queries.generated\";\n\n// React Router loader function\nexport async function loader({ params }: { params: { id: string } }) {\n return preloadQuery({\n query: GET_DOG,\n variables: { id: params.id },\n });\n}\n\n// Route component\nexport default function DogRoute() {\n const queryRef = useLoaderData();\n\n return (\n \n
\n );\n}\n```\n\n### Preventing Route Transitions Until Query Loads\n\nUse `preloadQuery.toPromise(queryRef)` to prevent route transitions until the query finishes loading:\n\n```tsx\nexport async function loader({ params }: { params: { id: string } }) {\n const queryRef = preloadQuery({\n query: GET_DOG,\n variables: { id: params.id },\n });\n\n // Wait for the query to complete before transitioning\n return preloadQuery.toPromise(queryRef);\n}\n```\n\nWhen `preloadQuery.toPromise()` is used, the route transition waits for the query to complete, and the data renders immediately without showing a loading fallback.\n\n> **Note**: `preloadQuery.toPromise()` resolves with the `queryRef` itself (not the data) to encourage using `useReadQuery` for cache updates. If you need raw query data in your loader, use `client.query()` directly.\n\n### With Next.js Server Components\n\n> **Note**: For Next.js App Router, use the `PreloadQuery` component from `@apollo/client-integration-nextjs` instead. See [integration-nextjs.md](./integration-nextjs.md) for details.\n\n## useQueryRefHandlers\n\nThe `useQueryRefHandlers` hook provides access to `refetch` and `fetchMore` functions for queries initiated with `preloadQuery`, `useBackgroundQuery`, or `useLoadableQuery`. This is useful when you need to refetch or paginate data in components where the `queryRef` is passed through.\n\n> **Important:** Always call `useQueryRefHandlers` before `useReadQuery`. These two hooks interact with the same `queryRef`, and calling them in the wrong order could cause subtle bugs.\n\n### Basic Usage\n\n```tsx\nimport { useQueryRefHandlers } from \"@apollo/client/react\";\n\nfunction Breeds({ queryRef }: { queryRef: QueryRef{data.dog.name}
\nBreed: {data.dog.breed}
\n\n {\n startTransition(() => {\n refetch();\n });\n }}\n >\n {isPending ? \"Refetching...\" : \"Refetch breeds\"}\n \n
\n );\n}\n```\n\n### With Pagination\n\nUse `fetchMore` to implement pagination:\n\n```tsx\nfunction Posts({ queryRef }: { queryRef: QueryRef- \n {data.breeds.map((breed) => (\n
- {breed.name} \n ))}\n
\n {\n startTransition(() => {\n fetchMore({\n variables: {\n offset: data.posts.length,\n },\n });\n });\n }}\n >\n {isPending ? \"Loading...\" : \"Load more\"}\n \n
\n );\n}\n```\n\n### When to Use\n\n- **Preloaded queries**: Access refetch/fetchMore for queries initiated with `preloadQuery`\n- **Background queries**: Use in child components receiving `queryRef` from `useBackgroundQuery`\n- **Loadable queries**: Refetch or paginate queries initiated with `useLoadableQuery`\n- **React transitions**: Integrate with transitions to avoid showing loading fallbacks during refetches\n\n## Distinguishing Queries with queryKey\n\nApollo Client uses the combination of `query` and `variables` to uniquely identify each query. When multiple components use the same `query` and `variables`, they share the same identity and suspend at the same time, regardless of which component initiates the request.\n\nUse the `queryKey` option to ensure each hook has a unique identity:\n\n```tsx\nfunction UserProfile() {\n // First query with unique key\n const { data: userData } = useSuspenseQuery(GET_USER, {\n variables: { id: \"1\" },\n queryKey: [\"user-profile\"],\n });\n\n // Second query with same query and variables but different key\n const { data: userPreview } = useSuspenseQuery(GET_USER, {\n variables: { id: \"1\" },\n queryKey: [\"user-preview\"],\n });\n\n return (\n - \n {data.posts.map((post) => (\n
- {post.title} \n ))}\n
\n
\n );\n}\n```\n\n### When to Use\n\n- **Multiple instances**: When rendering multiple components that use the same query and variables\n- **Preventing shared suspension**: When you want independent control over when each query suspends\n- **Separate cache entries**: When you need to maintain separate cache states for the same query\n\n> **Note**: Each item in the `queryKey` array must be a stable identifier to prevent infinite fetches.\n\n## Suspense Boundaries and Error Handling\n\n### Suspense Boundaries\n\nWrap components that use Suspense hooks with `\n
\n )}\n >\n Something went wrong
\n{error.message}
\nName: {data?.dog?.name ?? \"Unknown\"}
\n {error && Warning: {error.message}
}\n \n );\n}\n```\n\n## Transitions\n\nUse React transitions to avoid showing loading UI when updating state. Transitions keep the previous UI visible while new data is fetching.\n\n### Using startTransition\n\n```tsx\nimport { useState, Suspense, startTransition } from \"react\";\n\nfunction DogSelector() {\n const { data } = useSuspenseQuery(GET_DOGS);\n const [selectedDog, setSelectedDog] = useState(data.dogs[0].id);\n\n return (\n <>\n User: {data.user.name}
;\n}\n\nfunction PostsList({ queryRef }: { queryRef: QueryRef- \n {data.posts.map((post) => (\n
- {post.title} \n ))}\n
Select a user
;\n }\n\n returnSelect a user
;\n }\n\n return (\n- {data?.users.map((user) =>
- {user.name} )}
{data.user.name}
;\n\n// Or use optional chaining\nreturn {data?.user?.name}
;\n```\n","docs/agent-skills/apollo-client/references/typescript-codegen.md":"# TypeScript Code Generation\n\nThis guide covers setting up GraphQL Code Generator for type-safe Apollo Client usage with TypeScript.\n\n## Installation\n\n```bash\nnpm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node\n```\n\n## Configuration\n\nCreate a `codegen.ts` file in your project root:\n\n```typescript\n// codegen.ts\nimport { CodegenConfig } from \"@graphql-codegen/cli\";\n\nconst config: CodegenConfig = {\n overwrite: true,\n schema: \"{data?.user.name}
;\n}\n```\n\n## Important Notes\n\n- The typed-document-node plugin might have a bundle size tradeoff but can prevent inconsistencies and is best suited for usage with LLMs, so it is recommended for most applications.\n- See the [GraphQL Code Generator documentation](https://www.apollographql.com/docs/react/development-testing/graphql-codegen#recommended-starter-configuration) for other recommended configuration patterns if required.\n- Apollo Client hooks automatically infer types from `TypedDocumentNode` - never use manual generics like `useQuery\n {data?.posts.map((post) =>
\n );\n}\n```\n\n## Cache Manipulation\n\n### cache.readQuery\n\n```typescript\n// Read data from cache\nconst data = cache.readQuery({\n query: GET_TODOS,\n});\n\n// With variables\nconst userData = cache.readQuery({\n query: GET_USER,\n variables: { id: \"1\" },\n});\n```\n\n### cache.writeQuery\n\n```typescript\n// Write data to cache\ncache.writeQuery({\n query: GET_TODOS,\n data: {\n todos: [\n { __typename: \"Todo\", id: \"1\", text: \"Buy milk\", completed: false },\n ],\n },\n});\n\n// With variables\ncache.writeQuery({\n query: GET_USER,\n variables: { id: \"1\" },\n data: {\n user: { __typename: \"User\", id: \"1\", name: \"John\" },\n },\n});\n```\n\n### cache.readFragment / cache.writeFragment\n\n```typescript\n// Read a specific object - use cache.identify for safety\nconst user = cache.readFragment({\n id: cache.identify({ __typename: \"User\", id: \"1\" }),\n fragment: gql`\n fragment UserFragment on User {\n id\n name\n email\n }\n `,\n});\n\n// Apollo Client 4.1+: Use 'from' parameter (recommended)\nconst user = cache.readFragment({\n from: { __typename: \"User\", id: \"1\" },\n fragment: gql`\n fragment UserFragment on User {\n id\n name\n email\n }\n `,\n});\n\n// Update a specific object\ncache.writeFragment({\n id: cache.identify({ __typename: \"User\", id: \"1\" }),\n fragment: gql`\n fragment UpdateUser on User {\n name\n }\n `,\n data: {\n name: \"Jane\",\n },\n});\n\n// Apollo Client 4.1+: Use 'from' parameter (recommended)\ncache.writeFragment({\n from: { __typename: \"User\", id: \"1\" },\n fragment: gql`\n fragment UpdateUser on User {\n name\n }\n `,\n data: {\n name: \"Jane\",\n },\n});\n```\n\n### cache.modify\n\n```typescript\n// Modify fields directly\ncache.modify({\n id: cache.identify(user),\n fields: {\n // Set new value\n name: () => \"New Name\",\n\n // Transform existing value\n postCount: (existing) => existing + 1,\n\n // Delete field\n temporaryField: (_, { DELETE }) => DELETE,\n\n // Add to array\n friends: (existing, { toReference }) => [\n ...existing,\n toReference({ __typename: \"User\", id: \"2\" }),\n ],\n },\n});\n```\n\n### cache.evict\n\n```typescript\n// Remove object from cache\ncache.evict({ id: \"User:1\" });\n\n// Remove specific field\ncache.evict({ id: \"User:1\", fieldName: \"friends\" });\n\n// Remove with broadcast (trigger re-renders)\ncache.evict({ id: \"User:1\", broadcast: true });\n```\n\n## Garbage Collection\n\n### Manual Garbage Collection\n\n```typescript\n// After evicting objects, clean up dangling references\ncache.evict({ id: \"User:1\" });\ncache.gc();\n```\n\n### Retaining Objects\n\n```typescript\n// Prevent objects from being garbage collected\nconst release = cache.retain(\"User:1\");\n\n// Later, allow GC\nrelease();\ncache.gc();\n```\n\n### Inspecting Cache\n\n```typescript\n// Get all cached data\nconst cacheContents = cache.extract();\n\n// Restore cache state\ncache.restore(previousCacheContents);\n\n// Get identified object cache key\nconst userId = cache.identify({ __typename: \"User\", id: \"1\" });\n// Returns: 'User:1'\n```\n","isInternal":false,"tokens":2653,"sizeBytes":10903},{"name":"error-handling.md","path":"docs/agent-skills/apollo-client/references/error-handling.md","rawUrl":"https://raw.githubusercontent.com/apollographql/apollo-client/HEAD/docs/agent-skills/apollo-client/references/error-handling.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Error Handling Reference (Apollo Client 4.x)\n\nNote that Apollo Client 4.x handles errors differently than Apollo Client 3.x.\nThis reference documents the updated error handling mechanisms, error types, and best practices for managing errors in your Apollo Client applications.\nFor older Apollo Client 3.x error handling documentation, see [Apollo Client 3.x Error Handling](https://www.apollographql.com/docs/react/v3/data/error-handling).\n\n## Table of Contents\n\n- [Understanding Errors](#understanding-errors)\n- [Error Types](#error-types)\n- [Identifying Error Types](#identifying-error-types)\n- [GraphQL Error Policies](#graphql-error-policies)\n- [Error Links](#error-links)\n- [Retry Link](#retry-link)\n- [Error Boundaries](#error-boundaries)\n\n## Understanding Errors\n\nErrors in Apollo Client fall into two main categories: **GraphQL errors** and **network errors**. Each category has specific error classes that provide detailed information about what went wrong.\n\n### GraphQL Errors\n\nGraphQL errors are related to server-side execution of a GraphQL operation:\n\n- **Syntax errors** (e.g., malformed query)\n- **Validation errors** (e.g., query includes a non-existent schema field)\n- **Resolver errors** (e.g., error while populating a query field)\n\nIf a syntax or validation error occurs, the server doesn't execute the operation. If resolver errors occur, the server can still return partial data.\n\nExample server response with GraphQL error:\n\n```json\n{\n \"errors\": [\n {\n \"message\": \"Cannot query field \\\"nonexistentField\\\" on type \\\"Query\\\".\",\n \"locations\": [{ \"line\": 2, \"column\": 3 }],\n \"extensions\": {\n \"code\": \"GRAPHQL_VALIDATION_FAILED\"\n }\n }\n ],\n \"data\": null\n}\n```\n\nIn Apollo Client 4.x, GraphQL errors are represented by the [`CombinedGraphQLErrors`](https://apollographql.com/docs/react/api/errors/CombinedGraphQLErrors) error type.\n\n### Network Errors\n\nNetwork errors occur when attempting to communicate with your GraphQL server:\n\n- `4xx` or `5xx` HTTP response status codes\n- Network unavailability\n- JSON parsing failures\n- Custom errors from Apollo Link request handlers\n\nNetwork errors might be represented by special error types, but if an api such as the `fetch` API throws a native error (e.g., `TypeError`), Apollo Client will pass it through as-is.\nThrown values that don't fulfill the standard `ErrorLike` interface are wrapped in the [`UnconventionalError`](https://apollographql.com/docs/react/api/errors/UnconventionalError) class, which fulfills the `ErrorLike` interface. As such, you can expect any error returned by Apollo Client to fulfill the `ErrorLike` interface.\n\n```ts\nexport interface ErrorLike {\n message: string;\n name: string;\n stack?: string;\n}\n```\n\n## Error Types\n\nApollo Client 4.x provides specific error classes for different error scenarios:\n\n### CombinedGraphQLErrors\n\nRepresents GraphQL errors returned by the server. Most common error type in applications.\n\n```tsx\nimport { CombinedGraphQLErrors } from \"@apollo/client/errors\";\n\nfunction UserProfile({ userId }: { userId: string }) {\n const { data, error } = useQuery(GET_USER, {\n variables: { id: userId },\n });\n\n // no need to check for nullishness of error, CombinedGraphQLErrors.is handles that\n if (CombinedGraphQLErrors.is(error)) {\n // Handle GraphQL errors\n return (\n \n {error.graphQLErrors.map((err, i) => (\n
\n );\n }\n\n return data ? GraphQL Error: {err.message}
\n ))}\n\n
\n );\n}\n```\n\n### Avoid setting a Global Error Policy\n\nWhile it is possible to set a global error policy using `defaultOptions`, in practice this is discouraged as it can lead to unexpected behavior and type safety issues. The return types of the TypeScript hooks may change depending on the `errorPolicy` passed into the hook, and this can conceptually not take global `defaultOptions` error policies into account. As such, it is best to set the `errorPolicy` per operation as needed.\n\n## Error Links\n\nThe `ErrorLink` can be used to e.g. log error globally or perform specific side effects based on errors happening.\n\nAn `ErrorLink` can't be used to swallow errors fully, but it can be used to retry an operation after handling an error, in which case the error wouldn't propagate. Otherwise, the most common use for `ErrorLink` is logging.\n\n```ts\nimport { ErrorLink } from \"@apollo/client/link/error\";\n\nconst errorLink = new ErrorLink(({ error, operation, forward }) => {\n if (someCondition(error)) {\n // Retry the request, returning the new observable\n return forward(operation);\n }\n\n // Log the error for any unhandled GraphQL errors or network errors.\n console.log(`[Error]: ${error.message}`);\n\n // If nothing is returned from the error handler callback, the error will be\n // emitted from the link chain as normal.\n});\n```\n\n### Retry Link\n\nAlternatively, you can use the `RetryLink` from `@apollo/client/link/retry` to implement retry logic for failed operations.\n\n```typescript\nimport { RetryLink } from \"@apollo/client/link/retry\";\n\nconst retryLink = new RetryLink({\n delay: {\n initial: 300,\n max: Infinity,\n jitter: true,\n },\n attempts: {\n max: 5,\n retryIf: (error, operation) => {\n // Retry on network errors\n return !!error && operation.operationName !== \"SensitiveOperation\";\n },\n },\n});\n\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n link: from([retryLink, errorLink, httpLink]),\n});\n```\n\n### Custom Retry Logic\n\n```typescript\nconst retryLink = new RetryLink({\n attempts: (count, operation, error) => {\n // Don't retry mutations\n if (\n operation.query.definitions.some(\n (def) =>\n def.kind === \"OperationDefinition\" && def.operation === \"mutation\"\n )\n ) {\n return false;\n }\n\n // Retry up to 3 times on network errors\n return count < 3 && !!error;\n },\n delay: (count) => {\n // Exponential backoff\n return Math.min(1000 * Math.pow(2, count), 30000);\n },\n});\n```\n\n## Error Boundaries\n\nWhen using suspenseful hooks, you should use React Error Boundaries for graceful error handling.\n\n### Non-suspense per-Component Error Handling\n\n```tsx\nimport {\n CombinedGraphQLErrors,\n ServerError,\n ServerParseError,\n} from \"@apollo/client/errors\";\n\nfunction SafeUserList() {\n const { data, error, loading, refetch } = useQuery(GET_USERS, {\n errorPolicy: \"all\",\n notifyOnNetworkStatusChange: true,\n });\n\n // Handle network errors\n if (ServerError.is(error) || ServerParseError.is(error)) {\n return (\n Good: {data?.goodField}
\n {error &&Bad: {error.message}}\n \n {CombinedGraphQLErrors.is(error) && (\n \n Some data may be incomplete: {error.graphQLErrors[0].message}\n \n )}\n\n {loading &&
\n );\n}\n```\n","isInternal":false,"tokens":2525,"sizeBytes":11094},{"name":"fragments.md","path":"docs/agent-skills/apollo-client/references/fragments.md","rawUrl":"https://raw.githubusercontent.com/apollographql/apollo-client/HEAD/docs/agent-skills/apollo-client/references/fragments.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Fragments Reference\n\nGraphQL fragments define a set of fields for a specific type. In Apollo Client, fragments are especially powerful when colocated with components to define each component's data requirements independently, creating a clear separation of concerns and enabling better component composition.\n\n## Table of Contents\n\n- [What Are Fragments](#what-are-fragments)\n- [Basic Fragment Syntax](#basic-fragment-syntax)\n- [Fragment Colocation](#fragment-colocation)\n- [Fragment Reading Hooks](#fragment-reading-hooks)\n- [Data Masking](#data-masking)\n- [Fragment Registry](#fragment-registry)\n- [TypeScript Integration](#typescript-integration)\n- [Best Practices](#best-practices)\n\n## What Are Fragments\n\nA GraphQL fragment defines a set of fields for a specific GraphQL type. Fragments are defined on a specific GraphQL type and can be included in operations using the spread operator (`...`).\n\nIn Apollo Client, fragments serve a specific purpose:\n\n**Fragments are for colocation, not reuse.** Each component should declare its data needs in a dedicated fragment. This allows components to independently evolve their data requirements without creating artificial dependencies between unrelated parts of your application.\n\nFragments enable:\n\n1. **Component colocation**: Define the exact data requirements for a component alongside the component code\n2. **Independent evolution**: Change a component's data needs without affecting other components\n3. **Code organization**: Compose fragments together to build complete queries that mirror your component hierarchy\n\n## Basic Fragment Syntax\n\n### Defining a Fragment\n\n```typescript\nimport { gql } from \"@apollo/client\";\n\nconst USER_FRAGMENT = gql`\n fragment UserFields on User {\n id\n name\n email\n avatarUrl\n }\n`;\n```\n\nEvery fragment includes:\n\n- A unique name (`UserFields`)\n- The type it operates on (`User`)\n- The fields to select\n\n### Using Fragments in Queries\n\nInclude fragments in queries using the spread operator:\n\n```typescript\nconst GET_USER = gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n ...UserFields\n }\n }\n\n ${USER_FRAGMENT}\n`;\n```\n\nWhen using GraphQL Code Generator with the recommended configuration (typescript, typescript-operations, and typed-document-node plugins), fragments defined in your source files are automatically picked up and generated into typed document nodes. The generated fragment documents already include the fragment definition, so you don't need to interpolate them manually into queries.\n\n## Fragment Colocation\n\nFragment colocation is the practice of defining fragments in the same file as the component that uses them. This creates a clear contract between components and their data requirements.\n\n### Why Colocate Fragments\n\n- **Locality**: Data requirements live next to the code that uses them\n- **Maintainability**: Changes to component UI and data needs happen together\n- **Type safety**: TypeScript can infer exact types from colocated fragments\n- **Independence**: Components can evolve their data requirements without affecting other components\n\n### Colocation Pattern\n\nThe recommended pattern for colocating fragments with components:\n\n```tsx\nimport { gql, FragmentType } from \"@apollo/client\";\nimport { useSuspenseFragment } from \"@apollo/client/react\";\n\n// Fragment definition\n// This will be picked up by Codegen to create `UserCard_UserFragmentDoc` in `./fragments.generated.ts`.\n// As that generated fragment document is correctly typed, we use that in the code going forward.\n// This fragment will never be consumed in runtime code, so it is wrapped in `if (false)` so the bundler can omit it when bundling.\nif (false) {\n gql`\n fragment UserCard_user on User {\n id\n name\n email\n avatarUrl\n }\n `;\n}\n\n// This has been created from above fragment definition by CodeGen and is a correctly typed `TypedDocumentNode`\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated.ts\";\n\n// Component receives the (partially masked) parent object\nexport function UserCard({\n user,\n}: {\n user: FragmentType\n \n
\n );\n}\n```\n\n### Naming Convention\n\nA suggested naming pattern for fragments follows this convention:\n\n```text\n{ComponentName}_{propName}\n```\n\nWhere `propName` is the name of the prop the component receives containing the fragment data.\n\nExamples:\n\n- `UserCard_user` - Fragment for the `user` prop in the UserCard component\n- `PostList_posts` - Fragment for the `posts` prop in the PostList component\n- `CommentItem_comment` - Fragment for the `comment` prop in the CommentItem component\n\nThis convention makes it clear which component owns which fragment. However, you can choose a different naming convention based on your project's needs.\n\n**Note**: A component might accept fragment data through multiple props, in which case it would have multiple associated fragments. For example, a `CommentCard` component might accept both a `comment` prop and an `author` prop, resulting in `CommentCard_comment` and `CommentCard_author` fragments.\n\n### Composing Fragments\n\nParent components compose child fragments to build complete queries:\n\n```tsx\n// Child component\nimport { gql } from \"@apollo/client\";\n\nif (false) {\n gql`\n fragment UserAvatar_user on User {\n id\n avatarUrl\n name\n }\n `;\n}\n\n// Parent component composes child fragments\nif (false) {\n gql`\n fragment UserProfile_user on User {\n id\n name\n email\n bio\n ...UserAvatar_user\n }\n `;\n}\n\n// Page-level query composes all fragments\nif (false) {\n gql`\n query UserProfilePage($id: ID!) {\n user(id: $id) {\n ...UserProfile_user\n }\n }\n `;\n}\n```\n\nThis creates a hierarchy that mirrors your component tree.\n\n## Fragment Reading Hooks\n\nApollo Client provides hooks to read fragment data within components. These hooks work with data masking to ensure components only access the data they explicitly requested.\n\n### useSuspenseFragment\n\nFor components using Suspense and concurrent features:\n\n```tsx\nimport { useSuspenseFragment } from \"@apollo/client/react\";\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.name}
\n{data.email}
\n{data.name}
;\n}\n```\n\n### useFragment\n\nFor components not using Suspense:\n\n```tsx\nimport { useFragment } from \"@apollo/client/react\";\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentTypeLoading...
;\n }\n\n return {data.name}
;\n}\n```\n\nThe `complete` field indicates whether all fragment data is available in the cache.\n\n### Hook Options\n\nBoth hooks accept these options:\n\n```typescript\n{\n // The fragment document (required)\n fragment: TypedDocumentNode,\n\n // The fragment name (optional in most cases)\n // Only required if the fragment document contains multiple definitions\n fragmentName?: string,\n\n // The source data containing the fragment (required)\n // Can be a single object or an array of objects\n from: FragmentType{user.privateData}
;\n}\n```\n\nWith data masking:\n\n```tsx\n// ✅ With data masking - component can only access its fragment data\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.privateData}
;\n\n // Only fields from the fragment are accessible\n return {data.name}
;\n}\n```\n\n### Benefits of Data Masking\n\n- **Prevents over-rendering**: Components only re-render when their specific data changes\n- **Enforces boundaries**: Components can't accidentally depend on data they don't own\n- **Better refactoring**: Safe to modify parent queries without breaking child components\n- **Type safety**: TypeScript catches attempts to access unavailable fields\n\n## Fragment Registry\n\nThe fragment registry is an **alternative approach** to GraphQL Code Generator's automatic fragment inlining by name. It allows you to register fragments globally, making them available throughout your application by name reference.\n\n**Important**: GraphQL Code Generator automatically inlines fragments by name wherever they're used in your queries. Either approach is sufficient on its own—**you don't need to combine them**.\n\n### Creating a Fragment Registry\n\n```typescript\nimport { ApolloClient, InMemoryCache } from \"@apollo/client\";\nimport { createFragmentRegistry } from \"@apollo/client/cache\";\n\nexport const fragmentRegistry = createFragmentRegistry();\n\nconst client = new ApolloClient({\n cache: new InMemoryCache({\n fragments: fragmentRegistry,\n }),\n});\n```\n\n### Registering Fragments\n\nRegister fragments after defining them:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { fragmentRegistry } from \"./apollo/client\";\n\nconst USER_FRAGMENT = gql`\n fragment UserFields on User {\n id\n name\n email\n }\n`;\n\nfragmentRegistry.register(USER_FRAGMENT);\n```\n\nWith colocated fragments:\n\n```tsx\nimport { fragmentRegistry } from \"@/apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\n// Register the fragment globally\nfragmentRegistry.register(UserCard_UserFragmentDoc);\n```\n\n### Using Registered Fragments\n\nOnce registered, fragments can be referenced by name in queries without explicit imports:\n\n```tsx\n// Fragment is available by name because it's registered\nconst GET_USER = gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n ...UserCard_user\n }\n }\n`;\n```\n\n### Approaches for Fragment Composition\n\nThere are three approaches to make child fragments available in parent queries:\n\n1. **GraphQL Code Generator inlining** (Recommended): CodeGen automatically inlines fragments by name. No manual work needed—just reference fragments by name in your queries.\n\n2. **Fragment Registry**: Manually register fragments to make them available by name. Useful for runtime scenarios where CodeGen isn't available.\n\n3. **Manual interpolation**: Explicitly import and interpolate child fragments into parent fragments:\n\n ```typescript\n import { CHILD_FRAGMENT } from \"./ChildComponent\";\n\n const PARENT_FRAGMENT = gql`\n fragment Parent_data on Data {\n field\n ...Child_data\n }\n ${CHILD_FRAGMENT}\n `;\n ```\n\n### Pros and Cons\n\n**GraphQL Code Generator inlining**:\n\n- ✅ Less work: Automatic, no manual registration needed\n- ❌ Larger bundle: Fragments are inlined into every query that uses them\n\n**Fragment Registry**:\n\n- ✅ Smaller bundle: Fragments are registered once, referenced by name\n- ❌ More work: Requires manual registration of each fragment\n- ❌ May cause issues with lazy-loaded modules if the module is not loaded before the query is executed\n- ✅ Best for deeply nested component trees where bundle size matters\n\n**Manual interpolation**:\n\n- ❌ Most work: Manual imports and interpolation required\n- ✅ Explicit: Clear fragment dependencies in code\n\n### Recommendation\n\nFor most applications using GraphQL Code Generator (as shown in this guide), **use the automatic inlining**—it requires no additional setup and works seamlessly. Consider the fragment registry only if bundle size becomes a concern in applications with deeply nested component trees.\n\n## TypeScript Integration\n\nApollo Client provides strong TypeScript support for fragments through GraphQL Code Generator.\n\n### Generated Types\n\nGraphQL Code Generator produces typed fragment documents:\n\n```typescript\n// Generated file: fragments.generated.ts\nexport type UserCard_UserFragment = {\n __typename: \"User\";\n id: string;\n name: string;\n email: string;\n avatarUrl: string;\n} & { \" $fragmentName\"?: \"UserCard_UserFragment\" };\n\nexport const UserCard_UserFragmentDoc: TypedDocumentNode<\n UserCard_UserFragment,\n never\n>;\n```\n\n### Type-Safe Fragment Usage\n\nUse `FragmentType` to accept masked fragment data:\n\n```tsx\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.name}
;\n}\n```\n\n### Fragment Type Inference\n\nTypeScript infers types from fragment documents automatically:\n\n```tsx\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\n// Types are inferred from the fragment\nconst { data } = useSuspenseFragment({\n fragment: UserCard_UserFragmentDoc,\n from: user,\n});\n\n// data.name is string\n// data.email is string\n// data.nonExistentField is a TypeScript error\n```\n\n### Parent-Child Type Safety\n\nWhen passing fragment data from parent to child:\n\n```tsx\n// Parent query\nconst { data } = useSuspenseQuery(GET_USER);\n\n// TypeScript ensures the query includes UserCard_user fragment\n// before allowing it to be passed to UserCard\n{data.name}
;\n}\n```\n\n```tsx\n// ❌ Avoid: Component uses query hook\nfunction UserCard({ userId }: { userId: string }) {\n const { data } = useQuery(GET_USER, { variables: { id: userId } });\n return {data.user.name}
;\n}\n```\n\n### Request Only Required Fields\n\nKeep fragments minimal and only request fields the component actually uses:\n\n```tsx\n// ✅ Good: Only necessary fields\nif (false) {\n gql`\n fragment UserListItem_user on User {\n id\n name\n }\n `;\n}\n```\n\n```tsx\n// ❌ Avoid: Requesting unused fields\nif (false) {\n gql`\n fragment UserListItem_user on User {\n id\n name\n email\n bio\n friends {\n id\n name\n }\n posts {\n id\n title\n }\n }\n `;\n}\n```\n\n### Use @defer for Below-the-Fold Content\n\nThe `@defer` directive allows you to defer loading of non-critical fields, enabling faster initial page loads by prioritizing essential data. The deferred fields are delivered via incremental delivery and arrive after the non-deferred data, allowing the UI to progressively render as data becomes available.\n\nDefer slow fields that aren't immediately visible:\n\n```tsx\nif (false) {\n gql`\n query ProductPage($id: ID!) {\n product(id: $id) {\n id\n name\n price\n ...ProductReviews_product @defer\n }\n }\n `;\n}\n```\n\nThis allows the page to render quickly while reviews load in the background.\n\n### Handle Client-Only Fields\n\nUse the `@client` directive for fields resolved locally:\n\n```tsx\nif (false) {\n gql`\n fragment TodoItem_todo on Todo {\n id\n text\n completed\n isSelected @client\n }\n `;\n}\n```\n\n### Enable Data Masking for New Applications\n\nAlways enable data masking in new applications:\n\n```typescript\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n dataMasking: true,\n});\n```\n\nThis enforces proper boundaries from the start and prevents accidental coupling between components.\n\n## Apollo Client Data Masking vs GraphQL-Codegen Fragment Masking\n\nApollo Client's data masking and GraphQL Code Generator's fragment masking are different features that serve different purposes:\n\n### GraphQL-Codegen Fragment Masking\n\nGraphQL Code Generator's fragment masking (when using the client preset) is a **type-level** feature:\n\n- Masks data only at the TypeScript type level\n- The actual runtime data remains fully accessible on the object\n- Using their `useFragment` hook simply \"unmasks\" the data on a type level\n- Does not prevent accidental access to data at runtime\n- Parent components receive all data and pass it down\n- This means the parent component has to be subscribed to all data\n\n### Apollo Client Data Masking\n\nApollo Client's data masking is a **runtime** feature with significant performance benefits:\n\n- Removes data at the runtime level, not just the type level\n- The `useFragment` and `useSuspenseFragment` hooks create cache subscriptions\n- Parent objects are sparse and only contain unmasked data\n- Prevents accidental access to data that should be masked\n\n### Key Benefits of Apollo Client Data Masking\n\n**1. No Accidental Data Access**\n\nWith runtime data masking, masked fields are not present in the parent object at all. You cannot accidentally access them, even if you bypass TypeScript type checking.\n\n**2. Fewer Re-renders**\n\nApollo Client's approach creates more efficient subscriptions:\n\n- **Without data masking**: Parent component subscribes to all fields (including masked ones). When a masked child field changes, the parent re-renders to pass that runtime data down the tree.\n- **With data masking**: Parent component only subscribes to its own unmasked fields. Subscriptions on masked fields happen lower in the React component tree when the child component calls `useSuspenseFragment`. When a masked field changes, only the child component that subscribed to it re-renders.\n\n### Example\n\n```tsx\nimport { FragmentType } from \"@apollo/client\";\nimport { useSuspenseQuery, useSuspenseFragment } from \"@apollo/client/react\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction ParentComponent() {\n const { data } = useSuspenseQuery(GET_USER);\n\n // With Apollo Client data masking:\n // - data.user only contains unmasked fields\n // - Parent doesn't re-render when child-specific fields change\n\n return {data.name}
;\n}\n```\n\nThis granular subscription approach improves performance in large applications with deeply nested component trees.\n","isInternal":false,"tokens":4955,"sizeBytes":22674},{"name":"integration-client.md","path":"docs/agent-skills/apollo-client/references/integration-client.md","rawUrl":"https://raw.githubusercontent.com/apollographql/apollo-client/HEAD/docs/agent-skills/apollo-client/references/integration-client.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Apollo Client Integration for Client-Side Apps\n\nThis guide covers setting up Apollo Client in client-side React applications without server-side rendering (SSR). This includes applications using Vite, Parcel, Create React App, or other bundlers that don't implement SSR.\n\nFor applications with SSR, use one of the framework-specific integration guides instead:\n\n- [Next.js App Router](integration-nextjs.md)\n- [React Router Framework Mode](integration-react-router.md)\n- [TanStack Start](integration-tanstack-start.md)\n\n## Installation\n\n```bash\nnpm install @apollo/client graphql rxjs\n```\n\n## TypeScript Code Generation (optional but recommended)\n\nFor type-safe GraphQL operations with TypeScript, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\n## Setup Steps\n\n### Step 1: Create Client\n\n```typescript\nimport { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\";\n\n// Recommended: Use HttpOnly cookies for authentication\nconst httpLink = new HttpLink({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n credentials: \"include\", // Sends cookies with requests (secure when using HttpOnly cookies)\n});\n\nconst client = new ApolloClient({\n link: httpLink,\n cache: new InMemoryCache(),\n});\n```\n\nIf you need manual token management (less secure, only when HttpOnly cookies aren't available):\n\n```typescript\nimport { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\";\nimport { SetContextLink } from \"@apollo/client/link/context\";\n\nconst httpLink = new HttpLink({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n});\n\nconst authLink = new SetContextLink(({ headers }) => {\n const token = localStorage.getItem(\"token\");\n return {\n headers: {\n ...headers,\n authorization: token ? `Bearer ${token}` : \"\",\n },\n };\n});\n\nconst client = new ApolloClient({\n link: authLink.concat(httpLink),\n cache: new InMemoryCache(),\n});\n```\n\n### Step 2: Setup Provider\n\n```tsx\nimport { ApolloProvider } from \"@apollo/client\";\nimport App from \"./App\";\n\nfunction Root() {\n return (\n Loading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return (\n- {data?.users.map((user) =>
- {user.name} )}
Loading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return{data?.user.name}
;\n}\n```\n\n> **Note for TypeScript users**: Use [`dataState`](https://www.apollographql.com/docs/react/data/typescript#type-narrowing-data-with-datastate) for more robust type safety and better type narrowing in Apollo Client 4.x.\n\n### TypeScript Integration\n\nFor complete examples with loading, error handling, and `dataState` for type narrowing, see [Basic Query Usage](#basic-query-usage) above.\n\n#### Usage with Generated Types\n\nFor type-safe operations with code generation, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\nQuick example:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useQuery } from \"@apollo/client/react\";\nimport { GetUserDocument } from \"./queries.generated\";\n\n// Define your query with the if (false) pattern for code generation\nif (false) {\n gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n id\n name\n email\n }\n }\n `;\n}\n\nfunction UserProfile({ userId }: { userId: string }) {\n // Types are automatically inferred from GetUserDocument\n const { data } = useQuery(GetUserDocument, {\n variables: { id: userId },\n });\n\n return {data.user.name}
;\n}\n```\n\n#### Usage with Manual Type Annotations\n\nIf not using code generation, define types alongside your queries using `TypedDocumentNode`:\n\n```typescript\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\nimport { useQuery } from \"@apollo/client/react\";\n\ninterface GetUserData {\n user: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface GetUserVariables {\n id: string;\n}\n\n// Types should always be defined via TypedDocumentNode alongside your queries/mutations, not at the useQuery/useMutation call site\nconst GET_USER: TypedDocumentNode{data.user.name}
;\n}\n```\n\n## Basic Mutation Usage\n\n```tsx\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\nimport { useMutation } from \"@apollo/client/react\";\n\ninterface CreateUserMutation {\n createUser: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface CreateUserMutationVariables {\n input: {\n name: string;\n email: string;\n };\n}\n\nconst CREATE_USER: TypedDocumentNode<\n CreateUserMutation,\n CreateUserMutationVariables\n> = gql`\n mutation CreateUser($input: CreateUserInput!) {\n createUser(input: $input) {\n id\n name\n email\n }\n }\n`;\n\nfunction CreateUserForm() {\n const [createUser, { loading, error }] = useMutation(CREATE_USER);\n\n const handleSubmit = async (formData: FormData) => {\n const { data } = await createUser({\n variables: {\n input: {\n name: formData.get(\"name\") as string,\n email: formData.get(\"email\") as string,\n },\n },\n });\n if (data) {\n console.log(\"Created user:\", data.createUser);\n }\n };\n\n return (\n Error: {error.message}
}\n \n );\n}\n```\n\n## Client Configuration Options\n\n```typescript\nconst client = new ApolloClient({\n // Required: The cache implementation\n cache: new InMemoryCache({\n typePolicies: {\n Query: {\n fields: {\n // Field-level cache configuration\n },\n },\n },\n }),\n\n // Network layer\n link: new HttpLink({ uri: \"/graphql\" }),\n\n // Avoid defaultOptions if possible as they break TypeScript expectations.\n // Configure options per-query/mutation instead for better type safety.\n // defaultOptions: {\n // watchQuery: { fetchPolicy: 'cache-and-network' },\n // },\n\n // DevTools are enabled by default in development\n // Only configure when enabling in production\n devtools: {\n enabled: true, // Only needed for production\n },\n\n // Custom name for this client instance\n clientAwareness: {\n name: \"web-client\",\n version: \"1.0.0\",\n },\n});\n```\n\n## Important Considerations\n\n1. **Choose Your Hook Strategy:** Decide if your application should be based on Suspense. If it is, use suspenseful hooks like `useSuspenseQuery` (see [Suspense Hooks guide](suspense-hooks.md)), otherwise use non-suspenseful hooks like `useQuery` (see [Queries guide](queries.md)).\n\n2. **Client-Side Only:** This setup is for client-side apps without SSR. The Apollo Client instance is created once and reused throughout the application lifecycle.\n\n3. **Authentication:** Prefer HttpOnly cookies with `credentials: \"include\"` in `HttpLink` options to avoid exposing tokens to JavaScript. If manual token management is necessary, use `SetContextLink` to dynamically add authentication headers from `localStorage` or other client-side storage.\n\n4. **Environment Variables:** Store your GraphQL endpoint URL in environment variables for different environments (development, staging, production).\n\n5. **Error Handling:** Always handle `loading` and `error` states when using `useQuery` or `useLazyQuery`. For Suspense-based hooks (`useSuspenseQuery`), React handles this through `{data.user.name}
;\n}\n```\n\n### Override Next.js Fetch Options\n\nYou can override Next.js-specific `fetch` options per query using `context.fetchOptions`:\n\n```typescript\nconst { data } = await getClient().query({\n query: GET_USER,\n context: {\n fetchOptions: {\n next: { revalidate: 60 }, // Revalidate every 60 seconds\n },\n },\n});\n```\n\n## Setup for Client Components (SSR and Browser)\n\n### Step 1: Create Apollo Wrapper Component\n\nCreate `app/ApolloWrapper.tsx`:\n\n```typescript\n\"use client\";\n\nimport { HttpLink } from \"@apollo/client\";\nimport {\n ApolloNextAppProvider,\n ApolloClient,\n InMemoryCache,\n} from \"@apollo/client-integration-nextjs\";\n\nfunction makeClient() {\n const httpLink = new HttpLink({\n // Use an absolute URL for SSR\n uri: \"https://your-api.com/graphql\",\n fetchOptions: {\n // Optional: Next.js-specific fetch options\n // Note: This doesn't work with `export const dynamic = \"force-static\"`\n },\n });\n\n return new ApolloClient({\n cache: new InMemoryCache(),\n link: httpLink,\n });\n}\n\nexport function ApolloWrapper({ children }: React.PropsWithChildren) {\n return (\n {data.user.name}
;\n}\n```\n\n## Preloading Data from RSC to Client Components\n\nYou can preload data in React Server Components to populate the cache of your Client Components.\n\n### Step 1: Use PreloadQuery in Server Components\n\n```tsx\nimport { PreloadQuery } from \"./ApolloClient\";\nimport { Suspense } from \"react\";\n\nexport default async function Page() {\n return (\n {data.user.name}
;\n}\n```\n\n> **Important:** Data fetched this way should be considered client data and never referenced in Server Components. `PreloadQuery` prevents mixing server data and client data by creating a separate `ApolloClient` instance.\n\n### Using with useReadQuery\n\nFor advanced use cases, you can use `PreloadQuery` with `useReadQuery` to avoid request waterfalls:\n\n```tsx\n{data.user.name}
;\n}\n```\n\n## Handling Multipart Responses (@defer) in SSR\n\nWhen using the `@defer` directive, `useSuspenseQuery` will only suspend until the initial response is received. To handle deferred data properly, you have three strategies:\n\n### Strategy 1: Use PreloadQuery with useReadQuery\n\n`PreloadQuery` allows deferred data to be fully transported and streamed chunk-by-chunk.\n\n### Strategy 2: Remove @defer Fragments\n\nUse `RemoveMultipartDirectivesLink` to strip `@defer` directives from queries during SSR:\n\n```typescript\nimport { RemoveMultipartDirectivesLink } from \"@apollo/client-integration-nextjs\";\n\nnew RemoveMultipartDirectivesLink({\n stripDefer: true, // Default: true\n});\n```\n\nYou can exclude specific fragments from stripping by labeling them:\n\n```graphql\nquery myQuery {\n fastField\n ... @defer(label: \"SsrDontStrip1\") {\n slowField1\n }\n}\n```\n\n### Strategy 3: Wait for Deferred Data\n\nUse `AccumulateMultipartResponsesLink` to debounce the initial response:\n\n```typescript\nimport { AccumulateMultipartResponsesLink } from \"@apollo/client-integration-nextjs\";\n\nnew AccumulateMultipartResponsesLink({\n cutoffDelay: 100, // Wait up to 100ms for incremental data\n});\n```\n\n### Combined Approach: SSRMultipartLink\n\nCombine both strategies with `SSRMultipartLink`:\n\n```typescript\nimport { SSRMultipartLink } from \"@apollo/client-integration-nextjs\";\n\nnew SSRMultipartLink({\n stripDefer: true,\n cutoffDelay: 100,\n});\n```\n\n## Testing\n\nReset singleton instances between tests using the `resetApolloClientSingletons` helper:\n\n```typescript\nimport { resetApolloClientSingletons } from \"@apollo/client-integration-nextjs\";\n\nafterEach(resetApolloClientSingletons);\n```\n\n## Debugging\n\nEnable verbose logging in your `app/ApolloWrapper.tsx`:\n\n```typescript\nimport { setLogVerbosity } from \"@apollo/client\";\n\nsetLogVerbosity(\"debug\");\n```\n\n## Important Considerations\n\n1. **Separate RSC and SSR Queries:** Avoid overlapping queries between RSC and SSR. RSC queries don't update in the browser, while SSR queries can update dynamically as the cache changes.\n\n2. **Use Absolute URLs:** Always use absolute URLs in `HttpLink` for SSR, as relative URLs cannot be used in server-side rendering.\n\n3. **Streaming SSR:** For optimal performance, use `useSuspenseQuery` and `useFragment` to take advantage of React 18's streaming SSR capabilities.\n\n4. **Suspense Boundaries:** Place `Suspense` boundaries at meaningful places in your UI for the best user experience.\n","isInternal":false,"tokens":2013,"sizeBytes":8660},{"name":"integration-react-router.md","path":"docs/agent-skills/apollo-client/references/integration-react-router.md","rawUrl":"https://raw.githubusercontent.com/apollographql/apollo-client/HEAD/docs/agent-skills/apollo-client/references/integration-react-router.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Apollo Client Integration with React Router Framework Mode\n\nThis guide covers integrating Apollo Client in a React Router 7 application with support for modern streaming SSR.\n\n## Installation\n\nInstall Apollo Client and the React Router integration package:\n\n```bash\nnpm install @apollo/client-integration-react-router @apollo/client graphql rxjs\n```\n\n> **TypeScript users:** For type-safe GraphQL operations, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\n## Setup\n\n### Step 1: Create Apollo Configuration\n\nCreate an `app/apollo.ts` file that exports a `makeClient` function and an `apolloLoader`:\n\n```typescript\nimport { HttpLink, InMemoryCache } from \"@apollo/client\";\nimport {\n createApolloLoaderHandler,\n ApolloClient,\n} from \"@apollo/client-integration-react-router\";\n\n// `request` will be available on the server during SSR or in loaders, but not in the browser\nexport const makeClient = (request?: Request) => {\n return new ApolloClient({\n cache: new InMemoryCache(),\n link: new HttpLink({ uri: \"https://your-graphql-endpoint.com/graphql\" }),\n });\n};\n\nexport const apolloLoader = createApolloLoaderHandler(makeClient);\n```\n\n> **Important:** `ApolloClient` must be imported from `@apollo/client-integration-react-router`, not from `@apollo/client`.\n\n### Step 2: Reveal Entry Files\n\nRun the following command to create the entry files if they don't exist:\n\n```bash\nnpx react-router reveal\n```\n\nThis will create `app/entry.client.tsx` and `app/entry.server.tsx`.\n\n### Step 3: Configure Client Entry\n\nAdjust `app/entry.client.tsx` to wrap your app in `ApolloProvider`:\n\n```typescript\nimport { makeClient } from \"./apollo\";\nimport { ApolloProvider } from \"@apollo/client\";\nimport { StrictMode, startTransition } from \"react\";\nimport { hydrateRoot } from \"react-dom/client\";\nimport { HydratedRouter } from \"react-router/dom\";\n\nstartTransition(() => {\n const client = makeClient();\n hydrateRoot(\n document,\n \n
\n );\n}\n```\n\n> **Important:** To provide better TypeScript support, `apolloLoader` is a method that you need to call twice: `apolloLoader{data.user.name}
\n{data.user.email}
\n\n
\n );\n}\n```\n\n## Important Considerations\n\n1. **Import ApolloClient from Integration Package:** Always import `ApolloClient` from `@apollo/client-integration-react-router`, not from `@apollo/client`, to ensure proper SSR hydration.\n\n2. **TypeScript Support:** The `apolloLoader` function requires double invocation for proper TypeScript type inference: `apolloLoader{userData.user.name}
\nPosts
\n- \n {postsData.posts.map((post) => (\n
- {post.title} \n ))}\n
\n
\n );\n}\n```\n\n### Option 2: Direct useSuspenseQuery in Component\n\nYou can also use Apollo Client's suspenseful hooks directly in your component without a loader:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\nimport { createFileRoute } from \"@tanstack/react-router\";\nimport type { TypedDocumentNode } from \"@apollo/client\";\n\n// TypedDocumentNode definition with types\nconst GET_POSTS: TypedDocumentNode<{\n posts: Array<{ id: string; title: string; content: string }>;\n}> = gql`\n query GetPosts {\n posts {\n id\n title\n content\n }\n }\n`;\n\nexport const Route = createFileRoute(\"/posts\")({\n component: RouteComponent,\n});\n\nfunction RouteComponent() {\n const { data } = useSuspenseQuery(GET_POSTS);\n\n return (\n {data.user.name}
\n{data.user.email}
\n\n
\n );\n}\n```\n\n### Multiple Queries in a Loader\n\nYou can preload multiple queries in a single loader:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useReadQuery } from \"@apollo/client/react\";\nimport { createFileRoute } from \"@tanstack/react-router\";\n\n// TypedDocumentNode definitions omitted for brevity\n\nexport const Route = createFileRoute(\"/dashboard\")({\n component: RouteComponent,\n loader: ({ context: { preloadQuery } }) => {\n const userQueryRef = preloadQuery(GET_USER, {\n variables: { id: \"current\" },\n });\n\n const statsQueryRef = preloadQuery(GET_STATS, {\n variables: { period: \"month\" },\n });\n\n return {\n userQueryRef,\n statsQueryRef,\n };\n },\n});\n\nfunction RouteComponent() {\n const { userQueryRef, statsQueryRef } = Route.useLoaderData();\n const { data: userData } = useReadQuery(userQueryRef);\n const { data: statsData } = useReadQuery(statsQueryRef);\n\n return (\n Posts
\n- \n {data.posts.map((post) => (\n
- \n
{post.title}
\n{post.content}
\n \n ))}\n
\n
\n );\n}\n```\n\n### Using useQueryRefHandlers for Refetching\n\nWhen using `useReadQuery`, you can get refetch functionality from `useQueryRefHandlers`:\n\n> **Important:** Always call `useQueryRefHandlers` before `useReadQuery`. These two hooks interact with the same `queryRef`, and calling them in the wrong order could cause subtle bugs.\n\n```typescript\nimport { useReadQuery, useQueryRefHandlers, QueryRef } from \"@apollo/client/react\";\n\nfunction UserComponent({ queryRef }: { queryRef: QueryRefWelcome, {userData.user.name}
\n\n
\n Monthly Stats
\nViews: {statsData.stats.views}
\nClicks: {statsData.stats.clicks}
\n\n
\n );\n}\n```\n\n## Important Considerations\n\n1. **Import from Integration Package:** Always import `ApolloClient` and `InMemoryCache` from `@apollo/client-integration-tanstack-start`, not from `@apollo/client`, to ensure proper SSR hydration.\n\n2. **Context Type:** Use `createRootRouteWithContext{data.user.name}
\n \nError: {error.message}
}\n \n );\n}\n```\n\n### Return Tuple\n\n```typescript\nconst [\n mutateFunction, // Function to call to execute mutation\n {\n data, // Mutation result data\n loading, // True while mutation is in flight\n error, // ApolloError if mutation failed\n called, // True if mutation has been called\n reset, // Reset mutation state\n client, // Apollo Client instance\n },\n] = useMutation(MUTATION);\n```\n\n## Mutation Variables\n\n### Variables in Options\n\n```tsx\nconst [createUser] = useMutation(CREATE_USER, {\n variables: {\n input: {\n name: \"Default User\",\n email: \"default@example.com\",\n },\n },\n});\n\n// Call with default variables\nawait createUser();\n\n// Override variables\nawait createUser({\n variables: {\n input: {\n name: \"Custom User\",\n email: \"custom@example.com\",\n },\n },\n});\n```\n\n### TypeScript Types\n\nUse `TypedDocumentNode` instead of generic type parameters:\n\n```typescript\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\n\ninterface CreateUserData {\n createUser: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface CreateUserVariables {\n input: {\n name: string;\n email: string;\n };\n}\n\nconst CREATE_USER: TypedDocumentNode\n
\n );\n }\n\n return (\n \n );\n}\n```\n\n### Async/Await Pattern\n\nIf you only need the promise without using the hook's loading/data state, use `client.mutate` instead:\n\n```tsx\nimport { useApolloClient } from \"@apollo/client/react\";\n\nfunction CreatePost() {\n const client = useApolloClient();\n\n async function handleSubmit(formData: FormData) {\n try {\n const { data } = await client.mutate({\n mutation: CREATE_POST,\n variables: {\n input: {\n title: formData.get(\"title\"),\n content: formData.get(\"content\"),\n },\n },\n });\n console.log(\"Created:\", data.createPost);\n router.push(`/posts/${data.createPost.id}`);\n } catch (error) {\n console.error(\"Failed to create post:\", error);\n }\n }\n\n return (\n Post created: {data.createPost.title}
\n \nLoading...
;\n if (error) returnError: {error.message}
;\n\n return- {data?.dogs.map((dog) =>
- {dog.breed} )}
Error: {error.message}
;\n\n return\n {loading &&
\n );\n}\n```\n\n### Network Status\n\n```tsx\nimport { NetworkStatus } from \"@apollo/client\";\n\nfunction Dogs() {\n const { loading, error, data, networkStatus, refetch } = useQuery(GET_DOGS, {\n notifyOnNetworkStatusChange: true,\n });\n\n if (networkStatus === NetworkStatus.refetch) {\n return Refetching...
;\n }\n\n if (loading) returnLoading...
;\n if (error) returnError: {error.message}
;\n\n return (\n <>\n \n- \n {data.dogs.map((dog) => (\n
- {dog.breed} \n ))}\n
Loading...
;\n if (error) returnError: {error.message}
;\n\n return (\n\n {data?.dog && }\n \n
\n );\n}\n```\n\n### When to Use client.query Instead\n\nIf you only need the promise result and don't consume the loading/error/data states from the hook, use `client.query` instead:\n\n```tsx\nimport { useApolloClient } from \"@apollo/client/react\";\n\nfunction SearchDogs() {\n const client = useApolloClient();\n const [search, setSearch] = useState(\"\");\n\n const handleSearch = async () => {\n try {\n const { data } = await client.query({\n query: SEARCH_DOGS,\n variables: { query: search },\n });\n console.log(\"Found dogs:\", data.searchDogs);\n } catch (error) {\n console.error(\"Search failed:\", error);\n }\n };\n\n return (\n \n setSearch(e.target.value)} />\n \n
\n );\n}\n```\n\n## Polling and Refetching\n\n### Polling\n\n```tsx\nfunction LiveFeed() {\n const { data, startPolling, stopPolling } = useQuery(GET_FEED, {\n pollInterval: 5000, // Poll every 5 seconds\n });\n\n // Or control polling dynamically\n useEffect(() => {\n startPolling(5000);\n return () => stopPolling();\n }, [startPolling, stopPolling]);\n\n return \n \n \n
\n );\n}\n```\n\n## Fetch Policies\n\nControl how the query interacts with the cache.\n\n| Policy | Description |\n| ------------------- | ---------------------------------------------------------- |\n| `cache-first` | Return cached data if available, otherwise fetch (default) |\n| `cache-only` | Only return cached data, never fetch |\n| `cache-and-network` | Return cached data immediately, then fetch and update |\n| `network-only` | Always fetch, update cache, ignore cached data |\n| `no-cache` | Always fetch, never read or write cache |\n| `standby` | Same as cache-first but doesn't auto-update |\n\n### Usage Examples\n\n```tsx\n// Real-time data - always fetch\nconst { data } = useQuery(GET_NOTIFICATIONS, {\n fetchPolicy: \"network-only\",\n});\n\n// Static data - prefer cache\nconst { data } = useQuery(GET_CATEGORIES, {\n fetchPolicy: \"cache-first\",\n});\n\n// Show cached data while fetching fresh data\nconst { data, loading } = useQuery(GET_POSTS, {\n fetchPolicy: \"cache-and-network\",\n});\n\n// Fetch once, then use cache\nconst { data } = useQuery(GET_USER_PROFILE, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: \"cache-first\",\n});\n```\n\n### nextFetchPolicy\n\n```tsx\n// First request: network-only\n// Subsequent requests: cache-first\nconst { data } = useQuery(GET_POSTS, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: \"cache-first\",\n});\n\n// Or use a function for more control\nconst { data } = useQuery(GET_POSTS, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: (currentFetchPolicy, { reason, observable }) => {\n if (reason === \"after-fetch\") {\n return \"cache-first\";\n }\n return currentFetchPolicy;\n },\n});\n```\n\n## Conditional Queries\n\n### Using skipToken (Recommended)\n\nUse `skipToken` to conditionally skip queries without TypeScript issues:\n\n```tsx\nimport { skipToken } from \"@apollo/client\";\n\nfunction UserProfile({ userId }: { userId: string | null }) {\n const { data } = useQuery(\n GET_USER,\n !userId ? skipToken : (\n {\n variables: { id: userId },\n }\n )\n );\n\n return userId ? - {data?.dogs.map((dog) =>
- {dog.breed} )}
Select a user
;\n}\n```\n\n### Skip Option (Alternative)\n\n```tsx\nfunction UserProfile({ userId }: { userId: string | null }) {\n const { data } = useQuery(GET_USER, {\n variables: { id: userId! },\n skip: !userId, // Don't execute if no userId\n });\n\n return userId ?Select a user
;\n}\n```\n\n> **Note**: Using `skipToken` is preferred over `skip` as it avoids TypeScript issues with required variables and the non-null assertion operator.\n\n### SSR Skip\n\n```tsx\n// Skip during server-side rendering\nconst { data } = useQuery(GET_USER_LOCATION, {\n skip: typeof window === \"undefined\",\n ssr: false,\n});\n```\n","isInternal":false,"tokens":2641,"sizeBytes":10283},{"name":"state-management.md","path":"docs/agent-skills/apollo-client/references/state-management.md","rawUrl":"https://raw.githubusercontent.com/apollographql/apollo-client/HEAD/docs/agent-skills/apollo-client/references/state-management.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# State Management Reference\n\n## Table of Contents\n\n- [Reactive Variables](#reactive-variables)\n- [Local-Only Fields](#local-only-fields)\n- [LocalState Resolvers](#localstate-resolvers)\n- [Combining Remote and Local State](#combining-remote-and-local-state)\n- [useReactiveVar Hook](#usereactivevar-hook)\n\n## Reactive Variables\n\nReactive variables are a way to store local state outside of the Apollo Client cache while still triggering reactive updates.\n\n**Important**: Reactive variables store a single value that notifies `ApolloClient` instances when changed. They do not have separate values per ApolloClient instance. In multi-user environments like SSR, global or module-level reactive variables could be shared between users and cause data leaks. In frameworks that use SSR, always avoid storing reactive variables as globals.\n\n### Creating Reactive Variables\n\n```typescript\nimport { makeVar } from \"@apollo/client\";\n\n// Simple reactive variable\nexport const isLoggedInVar = makeVar\n
\n );\n}\n```\n\n### Local Field Read Functions (Type Policies)\n\nLocal field `read` functions are defined in entity-level type policies. You can use reactive variables inside these `read` functions, along with other calculations or derived values:\n\n```typescript\nconst cache = new InMemoryCache({\n typePolicies: {\n User: {\n fields: {\n // Simple local field from reactive variable\n isSelected: {\n read(_, { readField }) {\n const id = readField(\"id\");\n return selectedUsersVar().includes(id);\n },\n },\n\n // Computed local field (derived value)\n displayName: {\n read(_, { readField }) {\n const name = readField(\"name\");\n const email = readField(\"email\");\n return name || email?.split(\"@\")[0] || \"Anonymous\";\n },\n },\n },\n },\n },\n});\n```\n\n## LocalState Resolvers\n\n### Query-Level Local Resolvers\n\nQuery-level local fields can be defined using `LocalState` resolvers. **Note**: Do not read reactive variables inside LocalState resolvers - this is not a documented/tested feature. It might not behave as expected.\n\n```typescript\nimport { LocalState } from \"@apollo/client/local-state\";\n\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n localState: new LocalState({\n resolvers: {\n Query: {\n // Read from localStorage\n theme: () => {\n if (typeof window !== \"undefined\") {\n return localStorage.getItem(\"theme\") || \"light\";\n }\n return \"light\";\n },\n\n // Read from cache\n currentUser: (_, __, { cache }) => {\n if (typeof window === \"undefined\") return null;\n const userId = localStorage.getItem(\"currentUserId\");\n if (!userId) return null;\n return cache.readFragment({\n id: cache.identify({ __typename: \"User\", id: userId }),\n fragment: gql`\n fragment CurrentUser on User {\n id\n name\n email\n }\n `,\n });\n },\n\n // Compute value\n isOnline: () => {\n if (typeof navigator !== \"undefined\") {\n return navigator.onLine;\n }\n return true;\n },\n },\n },\n }),\n});\n```\n\n### Using Local Query Fields\n\n```tsx\nconst GET_AUTH_STATE = gql`\n query GetAuthState {\n isLoggedIn @client\n currentUser @client {\n id\n name\n email\n }\n }\n`;\n\nfunction AuthStatus() {\n const { data } = useQuery(GET_AUTH_STATE);\n\n if (!data?.isLoggedIn) {\n return {data?.user.displayName}
\n{data?.user.email}
\n\n
\n );\n}\n```\n\n### Multiple Reactive Variables\n\n```tsx\nfunction AppLayout() {\n const theme = useReactiveVar(themeVar);\n const sidebarOpen = useReactiveVar(sidebarOpenVar);\n const isLoggedIn = useReactiveVar(isLoggedInVar);\n\n return (\n Items: {totalItems}
\nTotal: ${totalPrice.toFixed(2)}
\n\n {isLoggedIn && sidebarOpen && \n \n
\n );\n}\n```\n","isInternal":false,"tokens":2379,"sizeBytes":10515},{"name":"suspense-hooks.md","path":"docs/agent-skills/apollo-client/references/suspense-hooks.md","rawUrl":"https://raw.githubusercontent.com/apollographql/apollo-client/HEAD/docs/agent-skills/apollo-client/references/suspense-hooks.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Suspense Hooks Reference\n\n> **Note**: Suspense hooks are the recommended approach for data fetching in modern React applications (React 18+). They provide cleaner code, better loading state handling, and enable streaming SSR.\n\n## Table of Contents\n\n- [useSuspenseQuery Hook](#usesuspensequery-hook)\n- [useBackgroundQuery and useReadQuery](#usebackgroundquery-and-usereadquery)\n- [useLoadableQuery](#useloadablequery)\n- [createQueryPreloader](#createquerypreloader)\n- [useQueryRefHandlers](#usequeryrefhandlers)\n- [Distinguishing Queries with queryKey](#distinguishing-queries-with-querykey)\n- [Suspense Boundaries and Error Handling](#suspense-boundaries-and-error-handling)\n- [Transitions](#transitions)\n- [Avoiding Request Waterfalls](#avoiding-request-waterfalls)\n- [Fetch Policies](#fetch-policies)\n- [Streaming SSR or React Server Components](#streaming-ssr-or-react-server-components)\n- [Conditional Queries](#conditional-queries)\n\n## useSuspenseQuery Hook\n\nThe `useSuspenseQuery` hook is the Suspense-ready replacement for `useQuery`. It initiates a network request and causes the component calling it to suspend while the request is made. Unlike `useQuery`, it does not return `loading` states—these are handled by React's Suspense boundaries and error boundaries.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\nimport { GET_DOG } from \"./queries.generated\";\n\nfunction App() {\n return (\n Name: {data.dog.name}
;\n}\n```\n\n### Return Object\n\n```typescript\nconst {\n data, // Query result data\n dataState, // With default options: \"complete\" | \"streaming\"\n // With returnPartialData: also \"partial\"\n // With errorPolicy \"all\" or \"ignore\": also \"empty\"\n error, // ApolloError (only when errorPolicy is \"all\" or \"ignore\")\n networkStatus, // NetworkStatus.ready, NetworkStatus.loading, etc.\n client, // Apollo Client instance\n refetch, // Function to re-execute query\n fetchMore, // Function for pagination\n} = useSuspenseQuery(QUERY, options);\n```\n\n### Key Differences from useQuery\n\n- **No `loading` boolean**: Component suspends instead of returning `loading: true`\n- **Error handling**: With default `errorPolicy` (`none`), errors are thrown and caught by error boundaries. With `errorPolicy: \"all\"` or `\"ignore\"`, the `error` property is returned and `data` may be `undefined`.\n- **`data` availability**: With default `errorPolicy` (`none`), `data` is guaranteed to be present when the component renders. With `errorPolicy: \"all\"` or `\"ignore\"`, when `dataState` is `empty`, `data` may be `undefined`.\n- **Suspense boundaries**: Must wrap component with `Name: {data.dog.name}
\n Breed: {data.dog.breed}
\n \n );\n}\n```\n\n### Rendering Partial Data\n\nUse `returnPartialData` to render immediately with partial cache data instead of suspending. The component will still suspend if there is no data in the cache.\n\n```tsx\nfunction Dog({ id }: { id: string }) {\n const { data } = useSuspenseQuery(GET_DOG, {\n variables: { id },\n returnPartialData: true,\n });\n\n return (\n <>\n Name: {data.dog?.name ?? \"Unknown\"}
\n {data.dog?.breed && Breed: {data.dog.breed}
}\n \n );\n}\n```\n\n## useBackgroundQuery and useReadQuery\n\nUse `useBackgroundQuery` with `useReadQuery` to avoid request waterfalls by starting a query in a parent component and reading the result in a child component. This pattern enables the parent to start fetching data before the child component renders.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useBackgroundQuery, useReadQuery } from \"@apollo/client/react\";\n\nfunction Parent() {\n // Start fetching immediately\n const [queryRef] = useBackgroundQuery(GET_DOG, {\n variables: { id: \"3\" },\n });\n\n return (\n Name: {data.dog.name}
;\n}\n```\n\n### When to Use\n\n- **Avoiding waterfalls**: Start fetching data in a parent (preferably above a suspense boundary) before child components render\n- **Preloading data**: Begin fetching before the component that needs the data is ready\n- **Parallel queries**: Start multiple queries at once in a parent component\n\n### Return Values\n\n`useBackgroundQuery` returns a tuple:\n\n```typescript\nconst [\n queryRef, // QueryRef to pass to useReadQuery\n { refetch, fetchMore, subscribeToMore }, // Helper functions\n] = useBackgroundQuery(QUERY, options);\n```\n\n`useReadQuery` returns the query result:\n\n```typescript\nconst {\n data, // Query result data (always defined)\n dataState, // \"complete\" | \"streaming\" | \"partial\" | \"empty\"\n error, // ApolloError (if errorPolicy allows)\n networkStatus, // Detailed network state (1-8)\n} = useReadQuery(queryRef);\n```\n\n## useLoadableQuery\n\nUse `useLoadableQuery` to imperatively load a query in response to a user interaction (like a button click) instead of on component mount.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useLoadableQuery, useReadQuery } from \"@apollo/client/react\";\nimport { GET_GREETING } from \"./queries.generated\";\n\nfunction App() {\n const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);\n\n return (\n <>\n {data.greeting.message}
;\n}\n```\n\n### Return Values\n\n```typescript\nconst [\n loadQuery, // Function to load the query\n queryRef, // QueryRef (null until loadQuery is called)\n { refetch, fetchMore, subscribeToMore, reset }, // Helper functions\n] = useLoadableQuery(QUERY, options);\n```\n\n### When to Use\n\n- **User-triggered fetching**: Load data in response to user actions\n- **Lazy loading**: Defer data fetching until it's actually needed\n- **Progressive disclosure**: Load data for UI elements that may not be initially visible\n\n## createQueryPreloader\n\nThe `createQueryPreloader` function creates a `preloadQuery` function that can be used to initiate queries outside of React components. This is useful for preloading data before a component renders, such as in route loaders or event handlers.\n\n### Basic Usage\n\n```tsx\nimport { ApolloClient, InMemoryCache } from \"@apollo/client\";\nimport { createQueryPreloader } from \"@apollo/client/react\";\n\nconst client = new ApolloClient({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n cache: new InMemoryCache(),\n});\n\n// Create a preload function\nexport const preloadQuery = createQueryPreloader(client);\n```\n\n### Using preloadQuery with Route Loaders\n\n> **Note**: This example applies to React Router in non-framework mode. For React Router framework mode, see [integration-react-router.md](./integration-react-router.md).\n\nUse the preload function with React Router's `loader` function to begin loading data during route transitions:\n\n```tsx\nimport { preloadQuery } from \"@/lib/apollo-client\";\nimport { GET_DOG } from \"./queries.generated\";\n\n// React Router loader function\nexport async function loader({ params }: { params: { id: string } }) {\n return preloadQuery({\n query: GET_DOG,\n variables: { id: params.id },\n });\n}\n\n// Route component\nexport default function DogRoute() {\n const queryRef = useLoaderData();\n\n return (\n \n
\n );\n}\n```\n\n### Preventing Route Transitions Until Query Loads\n\nUse `preloadQuery.toPromise(queryRef)` to prevent route transitions until the query finishes loading:\n\n```tsx\nexport async function loader({ params }: { params: { id: string } }) {\n const queryRef = preloadQuery({\n query: GET_DOG,\n variables: { id: params.id },\n });\n\n // Wait for the query to complete before transitioning\n return preloadQuery.toPromise(queryRef);\n}\n```\n\nWhen `preloadQuery.toPromise()` is used, the route transition waits for the query to complete, and the data renders immediately without showing a loading fallback.\n\n> **Note**: `preloadQuery.toPromise()` resolves with the `queryRef` itself (not the data) to encourage using `useReadQuery` for cache updates. If you need raw query data in your loader, use `client.query()` directly.\n\n### With Next.js Server Components\n\n> **Note**: For Next.js App Router, use the `PreloadQuery` component from `@apollo/client-integration-nextjs` instead. See [integration-nextjs.md](./integration-nextjs.md) for details.\n\n## useQueryRefHandlers\n\nThe `useQueryRefHandlers` hook provides access to `refetch` and `fetchMore` functions for queries initiated with `preloadQuery`, `useBackgroundQuery`, or `useLoadableQuery`. This is useful when you need to refetch or paginate data in components where the `queryRef` is passed through.\n\n> **Important:** Always call `useQueryRefHandlers` before `useReadQuery`. These two hooks interact with the same `queryRef`, and calling them in the wrong order could cause subtle bugs.\n\n### Basic Usage\n\n```tsx\nimport { useQueryRefHandlers } from \"@apollo/client/react\";\n\nfunction Breeds({ queryRef }: { queryRef: QueryRef{data.dog.name}
\nBreed: {data.dog.breed}
\n\n {\n startTransition(() => {\n refetch();\n });\n }}\n >\n {isPending ? \"Refetching...\" : \"Refetch breeds\"}\n \n
\n );\n}\n```\n\n### With Pagination\n\nUse `fetchMore` to implement pagination:\n\n```tsx\nfunction Posts({ queryRef }: { queryRef: QueryRef- \n {data.breeds.map((breed) => (\n
- {breed.name} \n ))}\n
\n {\n startTransition(() => {\n fetchMore({\n variables: {\n offset: data.posts.length,\n },\n });\n });\n }}\n >\n {isPending ? \"Loading...\" : \"Load more\"}\n \n
\n );\n}\n```\n\n### When to Use\n\n- **Preloaded queries**: Access refetch/fetchMore for queries initiated with `preloadQuery`\n- **Background queries**: Use in child components receiving `queryRef` from `useBackgroundQuery`\n- **Loadable queries**: Refetch or paginate queries initiated with `useLoadableQuery`\n- **React transitions**: Integrate with transitions to avoid showing loading fallbacks during refetches\n\n## Distinguishing Queries with queryKey\n\nApollo Client uses the combination of `query` and `variables` to uniquely identify each query. When multiple components use the same `query` and `variables`, they share the same identity and suspend at the same time, regardless of which component initiates the request.\n\nUse the `queryKey` option to ensure each hook has a unique identity:\n\n```tsx\nfunction UserProfile() {\n // First query with unique key\n const { data: userData } = useSuspenseQuery(GET_USER, {\n variables: { id: \"1\" },\n queryKey: [\"user-profile\"],\n });\n\n // Second query with same query and variables but different key\n const { data: userPreview } = useSuspenseQuery(GET_USER, {\n variables: { id: \"1\" },\n queryKey: [\"user-preview\"],\n });\n\n return (\n - \n {data.posts.map((post) => (\n
- {post.title} \n ))}\n
\n
\n );\n}\n```\n\n### When to Use\n\n- **Multiple instances**: When rendering multiple components that use the same query and variables\n- **Preventing shared suspension**: When you want independent control over when each query suspends\n- **Separate cache entries**: When you need to maintain separate cache states for the same query\n\n> **Note**: Each item in the `queryKey` array must be a stable identifier to prevent infinite fetches.\n\n## Suspense Boundaries and Error Handling\n\n### Suspense Boundaries\n\nWrap components that use Suspense hooks with `\n
\n )}\n >\n Something went wrong
\n{error.message}
\nName: {data?.dog?.name ?? \"Unknown\"}
\n {error && Warning: {error.message}
}\n \n );\n}\n```\n\n## Transitions\n\nUse React transitions to avoid showing loading UI when updating state. Transitions keep the previous UI visible while new data is fetching.\n\n### Using startTransition\n\n```tsx\nimport { useState, Suspense, startTransition } from \"react\";\n\nfunction DogSelector() {\n const { data } = useSuspenseQuery(GET_DOGS);\n const [selectedDog, setSelectedDog] = useState(data.dogs[0].id);\n\n return (\n <>\n User: {data.user.name}
;\n}\n\nfunction PostsList({ queryRef }: { queryRef: QueryRef- \n {data.posts.map((post) => (\n
- {post.title} \n ))}\n
Select a user
;\n }\n\n returnSelect a user
;\n }\n\n return (\n- {data?.users.map((user) =>
- {user.name} )}
{data.user.name}
;\n\n// Or use optional chaining\nreturn {data?.user?.name}
;\n```\n","isInternal":false,"tokens":2536,"sizeBytes":10750},{"name":"typescript-codegen.md","path":"docs/agent-skills/apollo-client/references/typescript-codegen.md","rawUrl":"https://raw.githubusercontent.com/apollographql/apollo-client/HEAD/docs/agent-skills/apollo-client/references/typescript-codegen.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# TypeScript Code Generation\n\nThis guide covers setting up GraphQL Code Generator for type-safe Apollo Client usage with TypeScript.\n\n## Installation\n\n```bash\nnpm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node\n```\n\n## Configuration\n\nCreate a `codegen.ts` file in your project root:\n\n```typescript\n// codegen.ts\nimport { CodegenConfig } from \"@graphql-codegen/cli\";\n\nconst config: CodegenConfig = {\n overwrite: true,\n schema: \"{data?.user.name}
;\n}\n```\n\n## Important Notes\n\n- The typed-document-node plugin might have a bundle size tradeoff but can prevent inconsistencies and is best suited for usage with LLMs, so it is recommended for most applications.\n- See the [GraphQL Code Generator documentation](https://www.apollographql.com/docs/react/development-testing/graphql-codegen#recommended-starter-configuration) for other recommended configuration patterns if required.\n- Apollo Client hooks automatically infer types from `TypedDocumentNode` - never use manual generics like `useQueryLoading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return{data?.user.name}
;\n}\n```\n\n### Basic Mutation\n\n```tsx\nimport { gql } from \"@apollo/client\";\nimport { useMutation } from \"@apollo/client/react\";\n\nconst CREATE_USER = gql`\n mutation CreateUser($input: CreateUserInput!) {\n createUser(input: $input) {\n id\n name\n }\n }\n`;\n\nfunction CreateUserForm() {\n const [createUser, { loading, error }] = useMutation(CREATE_USER);\n\n const handleSubmit = async (name: string) => {\n await createUser({ variables: { input: { name } } });\n };\n\n return ;\n}\n```\n\n### Suspense Query\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\n\nfunction UserProfile({ userId }: { userId: string }) {\n const { data } = useSuspenseQuery(GET_USER, {\n variables: { id: userId },\n });\n\n return {data.user.name}
;\n}\n\nfunction App() {\n return (\n \n {data?.posts.map((post) =>
\n );\n}\n```\n\n## Cache Manipulation\n\n### cache.readQuery\n\n```typescript\n// Read data from cache\nconst data = cache.readQuery({\n query: GET_TODOS,\n});\n\n// With variables\nconst userData = cache.readQuery({\n query: GET_USER,\n variables: { id: \"1\" },\n});\n```\n\n### cache.writeQuery\n\n```typescript\n// Write data to cache\ncache.writeQuery({\n query: GET_TODOS,\n data: {\n todos: [\n { __typename: \"Todo\", id: \"1\", text: \"Buy milk\", completed: false },\n ],\n },\n});\n\n// With variables\ncache.writeQuery({\n query: GET_USER,\n variables: { id: \"1\" },\n data: {\n user: { __typename: \"User\", id: \"1\", name: \"John\" },\n },\n});\n```\n\n### cache.readFragment / cache.writeFragment\n\n```typescript\n// Read a specific object - use cache.identify for safety\nconst user = cache.readFragment({\n id: cache.identify({ __typename: \"User\", id: \"1\" }),\n fragment: gql`\n fragment UserFragment on User {\n id\n name\n email\n }\n `,\n});\n\n// Apollo Client 4.1+: Use 'from' parameter (recommended)\nconst user = cache.readFragment({\n from: { __typename: \"User\", id: \"1\" },\n fragment: gql`\n fragment UserFragment on User {\n id\n name\n email\n }\n `,\n});\n\n// Update a specific object\ncache.writeFragment({\n id: cache.identify({ __typename: \"User\", id: \"1\" }),\n fragment: gql`\n fragment UpdateUser on User {\n name\n }\n `,\n data: {\n name: \"Jane\",\n },\n});\n\n// Apollo Client 4.1+: Use 'from' parameter (recommended)\ncache.writeFragment({\n from: { __typename: \"User\", id: \"1\" },\n fragment: gql`\n fragment UpdateUser on User {\n name\n }\n `,\n data: {\n name: \"Jane\",\n },\n});\n```\n\n### cache.modify\n\n```typescript\n// Modify fields directly\ncache.modify({\n id: cache.identify(user),\n fields: {\n // Set new value\n name: () => \"New Name\",\n\n // Transform existing value\n postCount: (existing) => existing + 1,\n\n // Delete field\n temporaryField: (_, { DELETE }) => DELETE,\n\n // Add to array\n friends: (existing, { toReference }) => [\n ...existing,\n toReference({ __typename: \"User\", id: \"2\" }),\n ],\n },\n});\n```\n\n### cache.evict\n\n```typescript\n// Remove object from cache\ncache.evict({ id: \"User:1\" });\n\n// Remove specific field\ncache.evict({ id: \"User:1\", fieldName: \"friends\" });\n\n// Remove with broadcast (trigger re-renders)\ncache.evict({ id: \"User:1\", broadcast: true });\n```\n\n## Garbage Collection\n\n### Manual Garbage Collection\n\n```typescript\n// After evicting objects, clean up dangling references\ncache.evict({ id: \"User:1\" });\ncache.gc();\n```\n\n### Retaining Objects\n\n```typescript\n// Prevent objects from being garbage collected\nconst release = cache.retain(\"User:1\");\n\n// Later, allow GC\nrelease();\ncache.gc();\n```\n\n### Inspecting Cache\n\n```typescript\n// Get all cached data\nconst cacheContents = cache.extract();\n\n// Restore cache state\ncache.restore(previousCacheContents);\n\n// Get identified object cache key\nconst userId = cache.identify({ __typename: \"User\", id: \"1\" });\n// Returns: 'User:1'\n```\n\n\n# Error Handling Reference (Apollo Client 4.x)\n\nNote that Apollo Client 4.x handles errors differently than Apollo Client 3.x.\nThis reference documents the updated error handling mechanisms, error types, and best practices for managing errors in your Apollo Client applications.\nFor older Apollo Client 3.x error handling documentation, see [Apollo Client 3.x Error Handling](https://www.apollographql.com/docs/react/v3/data/error-handling).\n\n## Table of Contents\n\n- [Understanding Errors](#understanding-errors)\n- [Error Types](#error-types)\n- [Identifying Error Types](#identifying-error-types)\n- [GraphQL Error Policies](#graphql-error-policies)\n- [Error Links](#error-links)\n- [Retry Link](#retry-link)\n- [Error Boundaries](#error-boundaries)\n\n## Understanding Errors\n\nErrors in Apollo Client fall into two main categories: **GraphQL errors** and **network errors**. Each category has specific error classes that provide detailed information about what went wrong.\n\n### GraphQL Errors\n\nGraphQL errors are related to server-side execution of a GraphQL operation:\n\n- **Syntax errors** (e.g., malformed query)\n- **Validation errors** (e.g., query includes a non-existent schema field)\n- **Resolver errors** (e.g., error while populating a query field)\n\nIf a syntax or validation error occurs, the server doesn't execute the operation. If resolver errors occur, the server can still return partial data.\n\nExample server response with GraphQL error:\n\n```json\n{\n \"errors\": [\n {\n \"message\": \"Cannot query field \\\"nonexistentField\\\" on type \\\"Query\\\".\",\n \"locations\": [{ \"line\": 2, \"column\": 3 }],\n \"extensions\": {\n \"code\": \"GRAPHQL_VALIDATION_FAILED\"\n }\n }\n ],\n \"data\": null\n}\n```\n\nIn Apollo Client 4.x, GraphQL errors are represented by the [`CombinedGraphQLErrors`](https://apollographql.com/docs/react/api/errors/CombinedGraphQLErrors) error type.\n\n### Network Errors\n\nNetwork errors occur when attempting to communicate with your GraphQL server:\n\n- `4xx` or `5xx` HTTP response status codes\n- Network unavailability\n- JSON parsing failures\n- Custom errors from Apollo Link request handlers\n\nNetwork errors might be represented by special error types, but if an api such as the `fetch` API throws a native error (e.g., `TypeError`), Apollo Client will pass it through as-is.\nThrown values that don't fulfill the standard `ErrorLike` interface are wrapped in the [`UnconventionalError`](https://apollographql.com/docs/react/api/errors/UnconventionalError) class, which fulfills the `ErrorLike` interface. As such, you can expect any error returned by Apollo Client to fulfill the `ErrorLike` interface.\n\n```ts\nexport interface ErrorLike {\n message: string;\n name: string;\n stack?: string;\n}\n```\n\n## Error Types\n\nApollo Client 4.x provides specific error classes for different error scenarios:\n\n### CombinedGraphQLErrors\n\nRepresents GraphQL errors returned by the server. Most common error type in applications.\n\n```tsx\nimport { CombinedGraphQLErrors } from \"@apollo/client/errors\";\n\nfunction UserProfile({ userId }: { userId: string }) {\n const { data, error } = useQuery(GET_USER, {\n variables: { id: userId },\n });\n\n // no need to check for nullishness of error, CombinedGraphQLErrors.is handles that\n if (CombinedGraphQLErrors.is(error)) {\n // Handle GraphQL errors\n return (\n \n {error.graphQLErrors.map((err, i) => (\n
\n );\n }\n\n return data ? GraphQL Error: {err.message}
\n ))}\n\n
\n );\n}\n```\n\n### Avoid setting a Global Error Policy\n\nWhile it is possible to set a global error policy using `defaultOptions`, in practice this is discouraged as it can lead to unexpected behavior and type safety issues. The return types of the TypeScript hooks may change depending on the `errorPolicy` passed into the hook, and this can conceptually not take global `defaultOptions` error policies into account. As such, it is best to set the `errorPolicy` per operation as needed.\n\n## Error Links\n\nThe `ErrorLink` can be used to e.g. log error globally or perform specific side effects based on errors happening.\n\nAn `ErrorLink` can't be used to swallow errors fully, but it can be used to retry an operation after handling an error, in which case the error wouldn't propagate. Otherwise, the most common use for `ErrorLink` is logging.\n\n```ts\nimport { ErrorLink } from \"@apollo/client/link/error\";\n\nconst errorLink = new ErrorLink(({ error, operation, forward }) => {\n if (someCondition(error)) {\n // Retry the request, returning the new observable\n return forward(operation);\n }\n\n // Log the error for any unhandled GraphQL errors or network errors.\n console.log(`[Error]: ${error.message}`);\n\n // If nothing is returned from the error handler callback, the error will be\n // emitted from the link chain as normal.\n});\n```\n\n### Retry Link\n\nAlternatively, you can use the `RetryLink` from `@apollo/client/link/retry` to implement retry logic for failed operations.\n\n```typescript\nimport { RetryLink } from \"@apollo/client/link/retry\";\n\nconst retryLink = new RetryLink({\n delay: {\n initial: 300,\n max: Infinity,\n jitter: true,\n },\n attempts: {\n max: 5,\n retryIf: (error, operation) => {\n // Retry on network errors\n return !!error && operation.operationName !== \"SensitiveOperation\";\n },\n },\n});\n\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n link: from([retryLink, errorLink, httpLink]),\n});\n```\n\n### Custom Retry Logic\n\n```typescript\nconst retryLink = new RetryLink({\n attempts: (count, operation, error) => {\n // Don't retry mutations\n if (\n operation.query.definitions.some(\n (def) =>\n def.kind === \"OperationDefinition\" && def.operation === \"mutation\"\n )\n ) {\n return false;\n }\n\n // Retry up to 3 times on network errors\n return count < 3 && !!error;\n },\n delay: (count) => {\n // Exponential backoff\n return Math.min(1000 * Math.pow(2, count), 30000);\n },\n});\n```\n\n## Error Boundaries\n\nWhen using suspenseful hooks, you should use React Error Boundaries for graceful error handling.\n\n### Non-suspense per-Component Error Handling\n\n```tsx\nimport {\n CombinedGraphQLErrors,\n ServerError,\n ServerParseError,\n} from \"@apollo/client/errors\";\n\nfunction SafeUserList() {\n const { data, error, loading, refetch } = useQuery(GET_USERS, {\n errorPolicy: \"all\",\n notifyOnNetworkStatusChange: true,\n });\n\n // Handle network errors\n if (ServerError.is(error) || ServerParseError.is(error)) {\n return (\n Good: {data?.goodField}
\n {error &&Bad: {error.message}}\n \n {CombinedGraphQLErrors.is(error) && (\n \n Some data may be incomplete: {error.graphQLErrors[0].message}\n \n )}\n\n {loading &&
\n );\n}\n```\n\n\n# Fragments Reference\n\nGraphQL fragments define a set of fields for a specific type. In Apollo Client, fragments are especially powerful when colocated with components to define each component's data requirements independently, creating a clear separation of concerns and enabling better component composition.\n\n## Table of Contents\n\n- [What Are Fragments](#what-are-fragments)\n- [Basic Fragment Syntax](#basic-fragment-syntax)\n- [Fragment Colocation](#fragment-colocation)\n- [Fragment Reading Hooks](#fragment-reading-hooks)\n- [Data Masking](#data-masking)\n- [Fragment Registry](#fragment-registry)\n- [TypeScript Integration](#typescript-integration)\n- [Best Practices](#best-practices)\n\n## What Are Fragments\n\nA GraphQL fragment defines a set of fields for a specific GraphQL type. Fragments are defined on a specific GraphQL type and can be included in operations using the spread operator (`...`).\n\nIn Apollo Client, fragments serve a specific purpose:\n\n**Fragments are for colocation, not reuse.** Each component should declare its data needs in a dedicated fragment. This allows components to independently evolve their data requirements without creating artificial dependencies between unrelated parts of your application.\n\nFragments enable:\n\n1. **Component colocation**: Define the exact data requirements for a component alongside the component code\n2. **Independent evolution**: Change a component's data needs without affecting other components\n3. **Code organization**: Compose fragments together to build complete queries that mirror your component hierarchy\n\n## Basic Fragment Syntax\n\n### Defining a Fragment\n\n```typescript\nimport { gql } from \"@apollo/client\";\n\nconst USER_FRAGMENT = gql`\n fragment UserFields on User {\n id\n name\n email\n avatarUrl\n }\n`;\n```\n\nEvery fragment includes:\n\n- A unique name (`UserFields`)\n- The type it operates on (`User`)\n- The fields to select\n\n### Using Fragments in Queries\n\nInclude fragments in queries using the spread operator:\n\n```typescript\nconst GET_USER = gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n ...UserFields\n }\n }\n\n ${USER_FRAGMENT}\n`;\n```\n\nWhen using GraphQL Code Generator with the recommended configuration (typescript, typescript-operations, and typed-document-node plugins), fragments defined in your source files are automatically picked up and generated into typed document nodes. The generated fragment documents already include the fragment definition, so you don't need to interpolate them manually into queries.\n\n## Fragment Colocation\n\nFragment colocation is the practice of defining fragments in the same file as the component that uses them. This creates a clear contract between components and their data requirements.\n\n### Why Colocate Fragments\n\n- **Locality**: Data requirements live next to the code that uses them\n- **Maintainability**: Changes to component UI and data needs happen together\n- **Type safety**: TypeScript can infer exact types from colocated fragments\n- **Independence**: Components can evolve their data requirements without affecting other components\n\n### Colocation Pattern\n\nThe recommended pattern for colocating fragments with components:\n\n```tsx\nimport { gql, FragmentType } from \"@apollo/client\";\nimport { useSuspenseFragment } from \"@apollo/client/react\";\n\n// Fragment definition\n// This will be picked up by Codegen to create `UserCard_UserFragmentDoc` in `./fragments.generated.ts`.\n// As that generated fragment document is correctly typed, we use that in the code going forward.\n// This fragment will never be consumed in runtime code, so it is wrapped in `if (false)` so the bundler can omit it when bundling.\nif (false) {\n gql`\n fragment UserCard_user on User {\n id\n name\n email\n avatarUrl\n }\n `;\n}\n\n// This has been created from above fragment definition by CodeGen and is a correctly typed `TypedDocumentNode`\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated.ts\";\n\n// Component receives the (partially masked) parent object\nexport function UserCard({\n user,\n}: {\n user: FragmentType\n \n
\n );\n}\n```\n\n### Naming Convention\n\nA suggested naming pattern for fragments follows this convention:\n\n```text\n{ComponentName}_{propName}\n```\n\nWhere `propName` is the name of the prop the component receives containing the fragment data.\n\nExamples:\n\n- `UserCard_user` - Fragment for the `user` prop in the UserCard component\n- `PostList_posts` - Fragment for the `posts` prop in the PostList component\n- `CommentItem_comment` - Fragment for the `comment` prop in the CommentItem component\n\nThis convention makes it clear which component owns which fragment. However, you can choose a different naming convention based on your project's needs.\n\n**Note**: A component might accept fragment data through multiple props, in which case it would have multiple associated fragments. For example, a `CommentCard` component might accept both a `comment` prop and an `author` prop, resulting in `CommentCard_comment` and `CommentCard_author` fragments.\n\n### Composing Fragments\n\nParent components compose child fragments to build complete queries:\n\n```tsx\n// Child component\nimport { gql } from \"@apollo/client\";\n\nif (false) {\n gql`\n fragment UserAvatar_user on User {\n id\n avatarUrl\n name\n }\n `;\n}\n\n// Parent component composes child fragments\nif (false) {\n gql`\n fragment UserProfile_user on User {\n id\n name\n email\n bio\n ...UserAvatar_user\n }\n `;\n}\n\n// Page-level query composes all fragments\nif (false) {\n gql`\n query UserProfilePage($id: ID!) {\n user(id: $id) {\n ...UserProfile_user\n }\n }\n `;\n}\n```\n\nThis creates a hierarchy that mirrors your component tree.\n\n## Fragment Reading Hooks\n\nApollo Client provides hooks to read fragment data within components. These hooks work with data masking to ensure components only access the data they explicitly requested.\n\n### useSuspenseFragment\n\nFor components using Suspense and concurrent features:\n\n```tsx\nimport { useSuspenseFragment } from \"@apollo/client/react\";\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.name}
\n{data.email}
\n{data.name}
;\n}\n```\n\n### useFragment\n\nFor components not using Suspense:\n\n```tsx\nimport { useFragment } from \"@apollo/client/react\";\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentTypeLoading...
;\n }\n\n return {data.name}
;\n}\n```\n\nThe `complete` field indicates whether all fragment data is available in the cache.\n\n### Hook Options\n\nBoth hooks accept these options:\n\n```typescript\n{\n // The fragment document (required)\n fragment: TypedDocumentNode,\n\n // The fragment name (optional in most cases)\n // Only required if the fragment document contains multiple definitions\n fragmentName?: string,\n\n // The source data containing the fragment (required)\n // Can be a single object or an array of objects\n from: FragmentType{user.privateData}
;\n}\n```\n\nWith data masking:\n\n```tsx\n// ✅ With data masking - component can only access its fragment data\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.privateData}
;\n\n // Only fields from the fragment are accessible\n return {data.name}
;\n}\n```\n\n### Benefits of Data Masking\n\n- **Prevents over-rendering**: Components only re-render when their specific data changes\n- **Enforces boundaries**: Components can't accidentally depend on data they don't own\n- **Better refactoring**: Safe to modify parent queries without breaking child components\n- **Type safety**: TypeScript catches attempts to access unavailable fields\n\n## Fragment Registry\n\nThe fragment registry is an **alternative approach** to GraphQL Code Generator's automatic fragment inlining by name. It allows you to register fragments globally, making them available throughout your application by name reference.\n\n**Important**: GraphQL Code Generator automatically inlines fragments by name wherever they're used in your queries. Either approach is sufficient on its own—**you don't need to combine them**.\n\n### Creating a Fragment Registry\n\n```typescript\nimport { ApolloClient, InMemoryCache } from \"@apollo/client\";\nimport { createFragmentRegistry } from \"@apollo/client/cache\";\n\nexport const fragmentRegistry = createFragmentRegistry();\n\nconst client = new ApolloClient({\n cache: new InMemoryCache({\n fragments: fragmentRegistry,\n }),\n});\n```\n\n### Registering Fragments\n\nRegister fragments after defining them:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { fragmentRegistry } from \"./apollo/client\";\n\nconst USER_FRAGMENT = gql`\n fragment UserFields on User {\n id\n name\n email\n }\n`;\n\nfragmentRegistry.register(USER_FRAGMENT);\n```\n\nWith colocated fragments:\n\n```tsx\nimport { fragmentRegistry } from \"@/apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\n// Register the fragment globally\nfragmentRegistry.register(UserCard_UserFragmentDoc);\n```\n\n### Using Registered Fragments\n\nOnce registered, fragments can be referenced by name in queries without explicit imports:\n\n```tsx\n// Fragment is available by name because it's registered\nconst GET_USER = gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n ...UserCard_user\n }\n }\n`;\n```\n\n### Approaches for Fragment Composition\n\nThere are three approaches to make child fragments available in parent queries:\n\n1. **GraphQL Code Generator inlining** (Recommended): CodeGen automatically inlines fragments by name. No manual work needed—just reference fragments by name in your queries.\n\n2. **Fragment Registry**: Manually register fragments to make them available by name. Useful for runtime scenarios where CodeGen isn't available.\n\n3. **Manual interpolation**: Explicitly import and interpolate child fragments into parent fragments:\n\n ```typescript\n import { CHILD_FRAGMENT } from \"./ChildComponent\";\n\n const PARENT_FRAGMENT = gql`\n fragment Parent_data on Data {\n field\n ...Child_data\n }\n ${CHILD_FRAGMENT}\n `;\n ```\n\n### Pros and Cons\n\n**GraphQL Code Generator inlining**:\n\n- ✅ Less work: Automatic, no manual registration needed\n- ❌ Larger bundle: Fragments are inlined into every query that uses them\n\n**Fragment Registry**:\n\n- ✅ Smaller bundle: Fragments are registered once, referenced by name\n- ❌ More work: Requires manual registration of each fragment\n- ❌ May cause issues with lazy-loaded modules if the module is not loaded before the query is executed\n- ✅ Best for deeply nested component trees where bundle size matters\n\n**Manual interpolation**:\n\n- ❌ Most work: Manual imports and interpolation required\n- ✅ Explicit: Clear fragment dependencies in code\n\n### Recommendation\n\nFor most applications using GraphQL Code Generator (as shown in this guide), **use the automatic inlining**—it requires no additional setup and works seamlessly. Consider the fragment registry only if bundle size becomes a concern in applications with deeply nested component trees.\n\n## TypeScript Integration\n\nApollo Client provides strong TypeScript support for fragments through GraphQL Code Generator.\n\n### Generated Types\n\nGraphQL Code Generator produces typed fragment documents:\n\n```typescript\n// Generated file: fragments.generated.ts\nexport type UserCard_UserFragment = {\n __typename: \"User\";\n id: string;\n name: string;\n email: string;\n avatarUrl: string;\n} & { \" $fragmentName\"?: \"UserCard_UserFragment\" };\n\nexport const UserCard_UserFragmentDoc: TypedDocumentNode<\n UserCard_UserFragment,\n never\n>;\n```\n\n### Type-Safe Fragment Usage\n\nUse `FragmentType` to accept masked fragment data:\n\n```tsx\nimport { FragmentType } from \"@apollo/client\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction UserCard({\n user,\n}: {\n user: FragmentType{data.name}
;\n}\n```\n\n### Fragment Type Inference\n\nTypeScript infers types from fragment documents automatically:\n\n```tsx\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\n// Types are inferred from the fragment\nconst { data } = useSuspenseFragment({\n fragment: UserCard_UserFragmentDoc,\n from: user,\n});\n\n// data.name is string\n// data.email is string\n// data.nonExistentField is a TypeScript error\n```\n\n### Parent-Child Type Safety\n\nWhen passing fragment data from parent to child:\n\n```tsx\n// Parent query\nconst { data } = useSuspenseQuery(GET_USER);\n\n// TypeScript ensures the query includes UserCard_user fragment\n// before allowing it to be passed to UserCard\n{data.name}
;\n}\n```\n\n```tsx\n// ❌ Avoid: Component uses query hook\nfunction UserCard({ userId }: { userId: string }) {\n const { data } = useQuery(GET_USER, { variables: { id: userId } });\n return {data.user.name}
;\n}\n```\n\n### Request Only Required Fields\n\nKeep fragments minimal and only request fields the component actually uses:\n\n```tsx\n// ✅ Good: Only necessary fields\nif (false) {\n gql`\n fragment UserListItem_user on User {\n id\n name\n }\n `;\n}\n```\n\n```tsx\n// ❌ Avoid: Requesting unused fields\nif (false) {\n gql`\n fragment UserListItem_user on User {\n id\n name\n email\n bio\n friends {\n id\n name\n }\n posts {\n id\n title\n }\n }\n `;\n}\n```\n\n### Use @defer for Below-the-Fold Content\n\nThe `@defer` directive allows you to defer loading of non-critical fields, enabling faster initial page loads by prioritizing essential data. The deferred fields are delivered via incremental delivery and arrive after the non-deferred data, allowing the UI to progressively render as data becomes available.\n\nDefer slow fields that aren't immediately visible:\n\n```tsx\nif (false) {\n gql`\n query ProductPage($id: ID!) {\n product(id: $id) {\n id\n name\n price\n ...ProductReviews_product @defer\n }\n }\n `;\n}\n```\n\nThis allows the page to render quickly while reviews load in the background.\n\n### Handle Client-Only Fields\n\nUse the `@client` directive for fields resolved locally:\n\n```tsx\nif (false) {\n gql`\n fragment TodoItem_todo on Todo {\n id\n text\n completed\n isSelected @client\n }\n `;\n}\n```\n\n### Enable Data Masking for New Applications\n\nAlways enable data masking in new applications:\n\n```typescript\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n dataMasking: true,\n});\n```\n\nThis enforces proper boundaries from the start and prevents accidental coupling between components.\n\n## Apollo Client Data Masking vs GraphQL-Codegen Fragment Masking\n\nApollo Client's data masking and GraphQL Code Generator's fragment masking are different features that serve different purposes:\n\n### GraphQL-Codegen Fragment Masking\n\nGraphQL Code Generator's fragment masking (when using the client preset) is a **type-level** feature:\n\n- Masks data only at the TypeScript type level\n- The actual runtime data remains fully accessible on the object\n- Using their `useFragment` hook simply \"unmasks\" the data on a type level\n- Does not prevent accidental access to data at runtime\n- Parent components receive all data and pass it down\n- This means the parent component has to be subscribed to all data\n\n### Apollo Client Data Masking\n\nApollo Client's data masking is a **runtime** feature with significant performance benefits:\n\n- Removes data at the runtime level, not just the type level\n- The `useFragment` and `useSuspenseFragment` hooks create cache subscriptions\n- Parent objects are sparse and only contain unmasked data\n- Prevents accidental access to data that should be masked\n\n### Key Benefits of Apollo Client Data Masking\n\n**1. No Accidental Data Access**\n\nWith runtime data masking, masked fields are not present in the parent object at all. You cannot accidentally access them, even if you bypass TypeScript type checking.\n\n**2. Fewer Re-renders**\n\nApollo Client's approach creates more efficient subscriptions:\n\n- **Without data masking**: Parent component subscribes to all fields (including masked ones). When a masked child field changes, the parent re-renders to pass that runtime data down the tree.\n- **With data masking**: Parent component only subscribes to its own unmasked fields. Subscriptions on masked fields happen lower in the React component tree when the child component calls `useSuspenseFragment`. When a masked field changes, only the child component that subscribed to it re-renders.\n\n### Example\n\n```tsx\nimport { FragmentType } from \"@apollo/client\";\nimport { useSuspenseQuery, useSuspenseFragment } from \"@apollo/client/react\";\nimport { UserCard_UserFragmentDoc } from \"./fragments.generated\";\n\nfunction ParentComponent() {\n const { data } = useSuspenseQuery(GET_USER);\n\n // With Apollo Client data masking:\n // - data.user only contains unmasked fields\n // - Parent doesn't re-render when child-specific fields change\n\n return {data.name}
;\n}\n```\n\nThis granular subscription approach improves performance in large applications with deeply nested component trees.\n\n\n# Apollo Client Integration for Client-Side Apps\n\nThis guide covers setting up Apollo Client in client-side React applications without server-side rendering (SSR). This includes applications using Vite, Parcel, Create React App, or other bundlers that don't implement SSR.\n\nFor applications with SSR, use one of the framework-specific integration guides instead:\n\n- [Next.js App Router](integration-nextjs.md)\n- [React Router Framework Mode](integration-react-router.md)\n- [TanStack Start](integration-tanstack-start.md)\n\n## Installation\n\n```bash\nnpm install @apollo/client graphql rxjs\n```\n\n## TypeScript Code Generation (optional but recommended)\n\nFor type-safe GraphQL operations with TypeScript, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\n## Setup Steps\n\n### Step 1: Create Client\n\n```typescript\nimport { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\";\n\n// Recommended: Use HttpOnly cookies for authentication\nconst httpLink = new HttpLink({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n credentials: \"include\", // Sends cookies with requests (secure when using HttpOnly cookies)\n});\n\nconst client = new ApolloClient({\n link: httpLink,\n cache: new InMemoryCache(),\n});\n```\n\nIf you need manual token management (less secure, only when HttpOnly cookies aren't available):\n\n```typescript\nimport { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\";\nimport { SetContextLink } from \"@apollo/client/link/context\";\n\nconst httpLink = new HttpLink({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n});\n\nconst authLink = new SetContextLink(({ headers }) => {\n const token = localStorage.getItem(\"token\");\n return {\n headers: {\n ...headers,\n authorization: token ? `Bearer ${token}` : \"\",\n },\n };\n});\n\nconst client = new ApolloClient({\n link: authLink.concat(httpLink),\n cache: new InMemoryCache(),\n});\n```\n\n### Step 2: Setup Provider\n\n```tsx\nimport { ApolloProvider } from \"@apollo/client\";\nimport App from \"./App\";\n\nfunction Root() {\n return (\n Loading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return (\n- {data?.users.map((user) =>
- {user.name} )}
Loading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return{data?.user.name}
;\n}\n```\n\n> **Note for TypeScript users**: Use [`dataState`](https://www.apollographql.com/docs/react/data/typescript#type-narrowing-data-with-datastate) for more robust type safety and better type narrowing in Apollo Client 4.x.\n\n### TypeScript Integration\n\nFor complete examples with loading, error handling, and `dataState` for type narrowing, see [Basic Query Usage](#basic-query-usage) above.\n\n#### Usage with Generated Types\n\nFor type-safe operations with code generation, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\nQuick example:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useQuery } from \"@apollo/client/react\";\nimport { GetUserDocument } from \"./queries.generated\";\n\n// Define your query with the if (false) pattern for code generation\nif (false) {\n gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n id\n name\n email\n }\n }\n `;\n}\n\nfunction UserProfile({ userId }: { userId: string }) {\n // Types are automatically inferred from GetUserDocument\n const { data } = useQuery(GetUserDocument, {\n variables: { id: userId },\n });\n\n return {data.user.name}
;\n}\n```\n\n#### Usage with Manual Type Annotations\n\nIf not using code generation, define types alongside your queries using `TypedDocumentNode`:\n\n```typescript\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\nimport { useQuery } from \"@apollo/client/react\";\n\ninterface GetUserData {\n user: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface GetUserVariables {\n id: string;\n}\n\n// Types should always be defined via TypedDocumentNode alongside your queries/mutations, not at the useQuery/useMutation call site\nconst GET_USER: TypedDocumentNode{data.user.name}
;\n}\n```\n\n## Basic Mutation Usage\n\n```tsx\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\nimport { useMutation } from \"@apollo/client/react\";\n\ninterface CreateUserMutation {\n createUser: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface CreateUserMutationVariables {\n input: {\n name: string;\n email: string;\n };\n}\n\nconst CREATE_USER: TypedDocumentNode<\n CreateUserMutation,\n CreateUserMutationVariables\n> = gql`\n mutation CreateUser($input: CreateUserInput!) {\n createUser(input: $input) {\n id\n name\n email\n }\n }\n`;\n\nfunction CreateUserForm() {\n const [createUser, { loading, error }] = useMutation(CREATE_USER);\n\n const handleSubmit = async (formData: FormData) => {\n const { data } = await createUser({\n variables: {\n input: {\n name: formData.get(\"name\") as string,\n email: formData.get(\"email\") as string,\n },\n },\n });\n if (data) {\n console.log(\"Created user:\", data.createUser);\n }\n };\n\n return (\n Error: {error.message}
}\n \n );\n}\n```\n\n## Client Configuration Options\n\n```typescript\nconst client = new ApolloClient({\n // Required: The cache implementation\n cache: new InMemoryCache({\n typePolicies: {\n Query: {\n fields: {\n // Field-level cache configuration\n },\n },\n },\n }),\n\n // Network layer\n link: new HttpLink({ uri: \"/graphql\" }),\n\n // Avoid defaultOptions if possible as they break TypeScript expectations.\n // Configure options per-query/mutation instead for better type safety.\n // defaultOptions: {\n // watchQuery: { fetchPolicy: 'cache-and-network' },\n // },\n\n // DevTools are enabled by default in development\n // Only configure when enabling in production\n devtools: {\n enabled: true, // Only needed for production\n },\n\n // Custom name for this client instance\n clientAwareness: {\n name: \"web-client\",\n version: \"1.0.0\",\n },\n});\n```\n\n## Important Considerations\n\n1. **Choose Your Hook Strategy:** Decide if your application should be based on Suspense. If it is, use suspenseful hooks like `useSuspenseQuery` (see [Suspense Hooks guide](suspense-hooks.md)), otherwise use non-suspenseful hooks like `useQuery` (see [Queries guide](queries.md)).\n\n2. **Client-Side Only:** This setup is for client-side apps without SSR. The Apollo Client instance is created once and reused throughout the application lifecycle.\n\n3. **Authentication:** Prefer HttpOnly cookies with `credentials: \"include\"` in `HttpLink` options to avoid exposing tokens to JavaScript. If manual token management is necessary, use `SetContextLink` to dynamically add authentication headers from `localStorage` or other client-side storage.\n\n4. **Environment Variables:** Store your GraphQL endpoint URL in environment variables for different environments (development, staging, production).\n\n5. **Error Handling:** Always handle `loading` and `error` states when using `useQuery` or `useLazyQuery`. For Suspense-based hooks (`useSuspenseQuery`), React handles this through `{data.user.name}
;\n}\n```\n\n### Override Next.js Fetch Options\n\nYou can override Next.js-specific `fetch` options per query using `context.fetchOptions`:\n\n```typescript\nconst { data } = await getClient().query({\n query: GET_USER,\n context: {\n fetchOptions: {\n next: { revalidate: 60 }, // Revalidate every 60 seconds\n },\n },\n});\n```\n\n## Setup for Client Components (SSR and Browser)\n\n### Step 1: Create Apollo Wrapper Component\n\nCreate `app/ApolloWrapper.tsx`:\n\n```typescript\n\"use client\";\n\nimport { HttpLink } from \"@apollo/client\";\nimport {\n ApolloNextAppProvider,\n ApolloClient,\n InMemoryCache,\n} from \"@apollo/client-integration-nextjs\";\n\nfunction makeClient() {\n const httpLink = new HttpLink({\n // Use an absolute URL for SSR\n uri: \"https://your-api.com/graphql\",\n fetchOptions: {\n // Optional: Next.js-specific fetch options\n // Note: This doesn't work with `export const dynamic = \"force-static\"`\n },\n });\n\n return new ApolloClient({\n cache: new InMemoryCache(),\n link: httpLink,\n });\n}\n\nexport function ApolloWrapper({ children }: React.PropsWithChildren) {\n return (\n {data.user.name}
;\n}\n```\n\n## Preloading Data from RSC to Client Components\n\nYou can preload data in React Server Components to populate the cache of your Client Components.\n\n### Step 1: Use PreloadQuery in Server Components\n\n```tsx\nimport { PreloadQuery } from \"./ApolloClient\";\nimport { Suspense } from \"react\";\n\nexport default async function Page() {\n return (\n {data.user.name}
;\n}\n```\n\n> **Important:** Data fetched this way should be considered client data and never referenced in Server Components. `PreloadQuery` prevents mixing server data and client data by creating a separate `ApolloClient` instance.\n\n### Using with useReadQuery\n\nFor advanced use cases, you can use `PreloadQuery` with `useReadQuery` to avoid request waterfalls:\n\n```tsx\n{data.user.name}
;\n}\n```\n\n## Handling Multipart Responses (@defer) in SSR\n\nWhen using the `@defer` directive, `useSuspenseQuery` will only suspend until the initial response is received. To handle deferred data properly, you have three strategies:\n\n### Strategy 1: Use PreloadQuery with useReadQuery\n\n`PreloadQuery` allows deferred data to be fully transported and streamed chunk-by-chunk.\n\n### Strategy 2: Remove @defer Fragments\n\nUse `RemoveMultipartDirectivesLink` to strip `@defer` directives from queries during SSR:\n\n```typescript\nimport { RemoveMultipartDirectivesLink } from \"@apollo/client-integration-nextjs\";\n\nnew RemoveMultipartDirectivesLink({\n stripDefer: true, // Default: true\n});\n```\n\nYou can exclude specific fragments from stripping by labeling them:\n\n```graphql\nquery myQuery {\n fastField\n ... @defer(label: \"SsrDontStrip1\") {\n slowField1\n }\n}\n```\n\n### Strategy 3: Wait for Deferred Data\n\nUse `AccumulateMultipartResponsesLink` to debounce the initial response:\n\n```typescript\nimport { AccumulateMultipartResponsesLink } from \"@apollo/client-integration-nextjs\";\n\nnew AccumulateMultipartResponsesLink({\n cutoffDelay: 100, // Wait up to 100ms for incremental data\n});\n```\n\n### Combined Approach: SSRMultipartLink\n\nCombine both strategies with `SSRMultipartLink`:\n\n```typescript\nimport { SSRMultipartLink } from \"@apollo/client-integration-nextjs\";\n\nnew SSRMultipartLink({\n stripDefer: true,\n cutoffDelay: 100,\n});\n```\n\n## Testing\n\nReset singleton instances between tests using the `resetApolloClientSingletons` helper:\n\n```typescript\nimport { resetApolloClientSingletons } from \"@apollo/client-integration-nextjs\";\n\nafterEach(resetApolloClientSingletons);\n```\n\n## Debugging\n\nEnable verbose logging in your `app/ApolloWrapper.tsx`:\n\n```typescript\nimport { setLogVerbosity } from \"@apollo/client\";\n\nsetLogVerbosity(\"debug\");\n```\n\n## Important Considerations\n\n1. **Separate RSC and SSR Queries:** Avoid overlapping queries between RSC and SSR. RSC queries don't update in the browser, while SSR queries can update dynamically as the cache changes.\n\n2. **Use Absolute URLs:** Always use absolute URLs in `HttpLink` for SSR, as relative URLs cannot be used in server-side rendering.\n\n3. **Streaming SSR:** For optimal performance, use `useSuspenseQuery` and `useFragment` to take advantage of React 18's streaming SSR capabilities.\n\n4. **Suspense Boundaries:** Place `Suspense` boundaries at meaningful places in your UI for the best user experience.\n\n\n# Apollo Client Integration with React Router Framework Mode\n\nThis guide covers integrating Apollo Client in a React Router 7 application with support for modern streaming SSR.\n\n## Installation\n\nInstall Apollo Client and the React Router integration package:\n\n```bash\nnpm install @apollo/client-integration-react-router @apollo/client graphql rxjs\n```\n\n> **TypeScript users:** For type-safe GraphQL operations, see the [TypeScript Code Generation guide](typescript-codegen.md).\n\n## Setup\n\n### Step 1: Create Apollo Configuration\n\nCreate an `app/apollo.ts` file that exports a `makeClient` function and an `apolloLoader`:\n\n```typescript\nimport { HttpLink, InMemoryCache } from \"@apollo/client\";\nimport {\n createApolloLoaderHandler,\n ApolloClient,\n} from \"@apollo/client-integration-react-router\";\n\n// `request` will be available on the server during SSR or in loaders, but not in the browser\nexport const makeClient = (request?: Request) => {\n return new ApolloClient({\n cache: new InMemoryCache(),\n link: new HttpLink({ uri: \"https://your-graphql-endpoint.com/graphql\" }),\n });\n};\n\nexport const apolloLoader = createApolloLoaderHandler(makeClient);\n```\n\n> **Important:** `ApolloClient` must be imported from `@apollo/client-integration-react-router`, not from `@apollo/client`.\n\n### Step 2: Reveal Entry Files\n\nRun the following command to create the entry files if they don't exist:\n\n```bash\nnpx react-router reveal\n```\n\nThis will create `app/entry.client.tsx` and `app/entry.server.tsx`.\n\n### Step 3: Configure Client Entry\n\nAdjust `app/entry.client.tsx` to wrap your app in `ApolloProvider`:\n\n```typescript\nimport { makeClient } from \"./apollo\";\nimport { ApolloProvider } from \"@apollo/client\";\nimport { StrictMode, startTransition } from \"react\";\nimport { hydrateRoot } from \"react-dom/client\";\nimport { HydratedRouter } from \"react-router/dom\";\n\nstartTransition(() => {\n const client = makeClient();\n hydrateRoot(\n document,\n \n
\n );\n}\n```\n\n> **Important:** To provide better TypeScript support, `apolloLoader` is a method that you need to call twice: `apolloLoader{data.user.name}
\n{data.user.email}
\n\n
\n );\n}\n```\n\n## Important Considerations\n\n1. **Import ApolloClient from Integration Package:** Always import `ApolloClient` from `@apollo/client-integration-react-router`, not from `@apollo/client`, to ensure proper SSR hydration.\n\n2. **TypeScript Support:** The `apolloLoader` function requires double invocation for proper TypeScript type inference: `apolloLoader{userData.user.name}
\nPosts
\n- \n {postsData.posts.map((post) => (\n
- {post.title} \n ))}\n
\n
\n );\n}\n```\n\n### Option 2: Direct useSuspenseQuery in Component\n\nYou can also use Apollo Client's suspenseful hooks directly in your component without a loader:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\nimport { createFileRoute } from \"@tanstack/react-router\";\nimport type { TypedDocumentNode } from \"@apollo/client\";\n\n// TypedDocumentNode definition with types\nconst GET_POSTS: TypedDocumentNode<{\n posts: Array<{ id: string; title: string; content: string }>;\n}> = gql`\n query GetPosts {\n posts {\n id\n title\n content\n }\n }\n`;\n\nexport const Route = createFileRoute(\"/posts\")({\n component: RouteComponent,\n});\n\nfunction RouteComponent() {\n const { data } = useSuspenseQuery(GET_POSTS);\n\n return (\n {data.user.name}
\n{data.user.email}
\n\n
\n );\n}\n```\n\n### Multiple Queries in a Loader\n\nYou can preload multiple queries in a single loader:\n\n```typescript\nimport { gql } from \"@apollo/client\";\nimport { useReadQuery } from \"@apollo/client/react\";\nimport { createFileRoute } from \"@tanstack/react-router\";\n\n// TypedDocumentNode definitions omitted for brevity\n\nexport const Route = createFileRoute(\"/dashboard\")({\n component: RouteComponent,\n loader: ({ context: { preloadQuery } }) => {\n const userQueryRef = preloadQuery(GET_USER, {\n variables: { id: \"current\" },\n });\n\n const statsQueryRef = preloadQuery(GET_STATS, {\n variables: { period: \"month\" },\n });\n\n return {\n userQueryRef,\n statsQueryRef,\n };\n },\n});\n\nfunction RouteComponent() {\n const { userQueryRef, statsQueryRef } = Route.useLoaderData();\n const { data: userData } = useReadQuery(userQueryRef);\n const { data: statsData } = useReadQuery(statsQueryRef);\n\n return (\n Posts
\n- \n {data.posts.map((post) => (\n
- \n
{post.title}
\n{post.content}
\n \n ))}\n
\n
\n );\n}\n```\n\n### Using useQueryRefHandlers for Refetching\n\nWhen using `useReadQuery`, you can get refetch functionality from `useQueryRefHandlers`:\n\n> **Important:** Always call `useQueryRefHandlers` before `useReadQuery`. These two hooks interact with the same `queryRef`, and calling them in the wrong order could cause subtle bugs.\n\n```typescript\nimport { useReadQuery, useQueryRefHandlers, QueryRef } from \"@apollo/client/react\";\n\nfunction UserComponent({ queryRef }: { queryRef: QueryRefWelcome, {userData.user.name}
\n\n
\n Monthly Stats
\nViews: {statsData.stats.views}
\nClicks: {statsData.stats.clicks}
\n\n
\n );\n}\n```\n\n## Important Considerations\n\n1. **Import from Integration Package:** Always import `ApolloClient` and `InMemoryCache` from `@apollo/client-integration-tanstack-start`, not from `@apollo/client`, to ensure proper SSR hydration.\n\n2. **Context Type:** Use `createRootRouteWithContext{data.user.name}
\n \nError: {error.message}
}\n \n );\n}\n```\n\n### Return Tuple\n\n```typescript\nconst [\n mutateFunction, // Function to call to execute mutation\n {\n data, // Mutation result data\n loading, // True while mutation is in flight\n error, // ApolloError if mutation failed\n called, // True if mutation has been called\n reset, // Reset mutation state\n client, // Apollo Client instance\n },\n] = useMutation(MUTATION);\n```\n\n## Mutation Variables\n\n### Variables in Options\n\n```tsx\nconst [createUser] = useMutation(CREATE_USER, {\n variables: {\n input: {\n name: \"Default User\",\n email: \"default@example.com\",\n },\n },\n});\n\n// Call with default variables\nawait createUser();\n\n// Override variables\nawait createUser({\n variables: {\n input: {\n name: \"Custom User\",\n email: \"custom@example.com\",\n },\n },\n});\n```\n\n### TypeScript Types\n\nUse `TypedDocumentNode` instead of generic type parameters:\n\n```typescript\nimport { gql, TypedDocumentNode } from \"@apollo/client\";\n\ninterface CreateUserData {\n createUser: {\n id: string;\n name: string;\n email: string;\n };\n}\n\ninterface CreateUserVariables {\n input: {\n name: string;\n email: string;\n };\n}\n\nconst CREATE_USER: TypedDocumentNode\n
\n );\n }\n\n return (\n \n );\n}\n```\n\n### Async/Await Pattern\n\nIf you only need the promise without using the hook's loading/data state, use `client.mutate` instead:\n\n```tsx\nimport { useApolloClient } from \"@apollo/client/react\";\n\nfunction CreatePost() {\n const client = useApolloClient();\n\n async function handleSubmit(formData: FormData) {\n try {\n const { data } = await client.mutate({\n mutation: CREATE_POST,\n variables: {\n input: {\n title: formData.get(\"title\"),\n content: formData.get(\"content\"),\n },\n },\n });\n console.log(\"Created:\", data.createPost);\n router.push(`/posts/${data.createPost.id}`);\n } catch (error) {\n console.error(\"Failed to create post:\", error);\n }\n }\n\n return (\n Post created: {data.createPost.title}
\n \nLoading...
;\n if (error) returnError: {error.message}
;\n\n return- {data?.dogs.map((dog) =>
- {dog.breed} )}
Error: {error.message}
;\n\n return\n {loading &&
\n );\n}\n```\n\n### Network Status\n\n```tsx\nimport { NetworkStatus } from \"@apollo/client\";\n\nfunction Dogs() {\n const { loading, error, data, networkStatus, refetch } = useQuery(GET_DOGS, {\n notifyOnNetworkStatusChange: true,\n });\n\n if (networkStatus === NetworkStatus.refetch) {\n return Refetching...
;\n }\n\n if (loading) returnLoading...
;\n if (error) returnError: {error.message}
;\n\n return (\n <>\n \n- \n {data.dogs.map((dog) => (\n
- {dog.breed} \n ))}\n
Loading...
;\n if (error) returnError: {error.message}
;\n\n return (\n\n {data?.dog && }\n \n
\n );\n}\n```\n\n### When to Use client.query Instead\n\nIf you only need the promise result and don't consume the loading/error/data states from the hook, use `client.query` instead:\n\n```tsx\nimport { useApolloClient } from \"@apollo/client/react\";\n\nfunction SearchDogs() {\n const client = useApolloClient();\n const [search, setSearch] = useState(\"\");\n\n const handleSearch = async () => {\n try {\n const { data } = await client.query({\n query: SEARCH_DOGS,\n variables: { query: search },\n });\n console.log(\"Found dogs:\", data.searchDogs);\n } catch (error) {\n console.error(\"Search failed:\", error);\n }\n };\n\n return (\n \n setSearch(e.target.value)} />\n \n
\n );\n}\n```\n\n## Polling and Refetching\n\n### Polling\n\n```tsx\nfunction LiveFeed() {\n const { data, startPolling, stopPolling } = useQuery(GET_FEED, {\n pollInterval: 5000, // Poll every 5 seconds\n });\n\n // Or control polling dynamically\n useEffect(() => {\n startPolling(5000);\n return () => stopPolling();\n }, [startPolling, stopPolling]);\n\n return \n \n \n
\n );\n}\n```\n\n## Fetch Policies\n\nControl how the query interacts with the cache.\n\n| Policy | Description |\n| ------------------- | ---------------------------------------------------------- |\n| `cache-first` | Return cached data if available, otherwise fetch (default) |\n| `cache-only` | Only return cached data, never fetch |\n| `cache-and-network` | Return cached data immediately, then fetch and update |\n| `network-only` | Always fetch, update cache, ignore cached data |\n| `no-cache` | Always fetch, never read or write cache |\n| `standby` | Same as cache-first but doesn't auto-update |\n\n### Usage Examples\n\n```tsx\n// Real-time data - always fetch\nconst { data } = useQuery(GET_NOTIFICATIONS, {\n fetchPolicy: \"network-only\",\n});\n\n// Static data - prefer cache\nconst { data } = useQuery(GET_CATEGORIES, {\n fetchPolicy: \"cache-first\",\n});\n\n// Show cached data while fetching fresh data\nconst { data, loading } = useQuery(GET_POSTS, {\n fetchPolicy: \"cache-and-network\",\n});\n\n// Fetch once, then use cache\nconst { data } = useQuery(GET_USER_PROFILE, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: \"cache-first\",\n});\n```\n\n### nextFetchPolicy\n\n```tsx\n// First request: network-only\n// Subsequent requests: cache-first\nconst { data } = useQuery(GET_POSTS, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: \"cache-first\",\n});\n\n// Or use a function for more control\nconst { data } = useQuery(GET_POSTS, {\n fetchPolicy: \"network-only\",\n nextFetchPolicy: (currentFetchPolicy, { reason, observable }) => {\n if (reason === \"after-fetch\") {\n return \"cache-first\";\n }\n return currentFetchPolicy;\n },\n});\n```\n\n## Conditional Queries\n\n### Using skipToken (Recommended)\n\nUse `skipToken` to conditionally skip queries without TypeScript issues:\n\n```tsx\nimport { skipToken } from \"@apollo/client\";\n\nfunction UserProfile({ userId }: { userId: string | null }) {\n const { data } = useQuery(\n GET_USER,\n !userId ? skipToken : (\n {\n variables: { id: userId },\n }\n )\n );\n\n return userId ? - {data?.dogs.map((dog) =>
- {dog.breed} )}
Select a user
;\n}\n```\n\n### Skip Option (Alternative)\n\n```tsx\nfunction UserProfile({ userId }: { userId: string | null }) {\n const { data } = useQuery(GET_USER, {\n variables: { id: userId! },\n skip: !userId, // Don't execute if no userId\n });\n\n return userId ?Select a user
;\n}\n```\n\n> **Note**: Using `skipToken` is preferred over `skip` as it avoids TypeScript issues with required variables and the non-null assertion operator.\n\n### SSR Skip\n\n```tsx\n// Skip during server-side rendering\nconst { data } = useQuery(GET_USER_LOCATION, {\n skip: typeof window === \"undefined\",\n ssr: false,\n});\n```\n\n\n# State Management Reference\n\n## Table of Contents\n\n- [Reactive Variables](#reactive-variables)\n- [Local-Only Fields](#local-only-fields)\n- [LocalState Resolvers](#localstate-resolvers)\n- [Combining Remote and Local State](#combining-remote-and-local-state)\n- [useReactiveVar Hook](#usereactivevar-hook)\n\n## Reactive Variables\n\nReactive variables are a way to store local state outside of the Apollo Client cache while still triggering reactive updates.\n\n**Important**: Reactive variables store a single value that notifies `ApolloClient` instances when changed. They do not have separate values per ApolloClient instance. In multi-user environments like SSR, global or module-level reactive variables could be shared between users and cause data leaks. In frameworks that use SSR, always avoid storing reactive variables as globals.\n\n### Creating Reactive Variables\n\n```typescript\nimport { makeVar } from \"@apollo/client\";\n\n// Simple reactive variable\nexport const isLoggedInVar = makeVar\n
\n );\n}\n```\n\n### Local Field Read Functions (Type Policies)\n\nLocal field `read` functions are defined in entity-level type policies. You can use reactive variables inside these `read` functions, along with other calculations or derived values:\n\n```typescript\nconst cache = new InMemoryCache({\n typePolicies: {\n User: {\n fields: {\n // Simple local field from reactive variable\n isSelected: {\n read(_, { readField }) {\n const id = readField(\"id\");\n return selectedUsersVar().includes(id);\n },\n },\n\n // Computed local field (derived value)\n displayName: {\n read(_, { readField }) {\n const name = readField(\"name\");\n const email = readField(\"email\");\n return name || email?.split(\"@\")[0] || \"Anonymous\";\n },\n },\n },\n },\n },\n});\n```\n\n## LocalState Resolvers\n\n### Query-Level Local Resolvers\n\nQuery-level local fields can be defined using `LocalState` resolvers. **Note**: Do not read reactive variables inside LocalState resolvers - this is not a documented/tested feature. It might not behave as expected.\n\n```typescript\nimport { LocalState } from \"@apollo/client/local-state\";\n\nconst client = new ApolloClient({\n cache: new InMemoryCache(),\n localState: new LocalState({\n resolvers: {\n Query: {\n // Read from localStorage\n theme: () => {\n if (typeof window !== \"undefined\") {\n return localStorage.getItem(\"theme\") || \"light\";\n }\n return \"light\";\n },\n\n // Read from cache\n currentUser: (_, __, { cache }) => {\n if (typeof window === \"undefined\") return null;\n const userId = localStorage.getItem(\"currentUserId\");\n if (!userId) return null;\n return cache.readFragment({\n id: cache.identify({ __typename: \"User\", id: userId }),\n fragment: gql`\n fragment CurrentUser on User {\n id\n name\n email\n }\n `,\n });\n },\n\n // Compute value\n isOnline: () => {\n if (typeof navigator !== \"undefined\") {\n return navigator.onLine;\n }\n return true;\n },\n },\n },\n }),\n});\n```\n\n### Using Local Query Fields\n\n```tsx\nconst GET_AUTH_STATE = gql`\n query GetAuthState {\n isLoggedIn @client\n currentUser @client {\n id\n name\n email\n }\n }\n`;\n\nfunction AuthStatus() {\n const { data } = useQuery(GET_AUTH_STATE);\n\n if (!data?.isLoggedIn) {\n return {data?.user.displayName}
\n{data?.user.email}
\n\n
\n );\n}\n```\n\n### Multiple Reactive Variables\n\n```tsx\nfunction AppLayout() {\n const theme = useReactiveVar(themeVar);\n const sidebarOpen = useReactiveVar(sidebarOpenVar);\n const isLoggedIn = useReactiveVar(isLoggedInVar);\n\n return (\n Items: {totalItems}
\nTotal: ${totalPrice.toFixed(2)}
\n\n {isLoggedIn && sidebarOpen && \n \n
\n );\n}\n```\n\n\n# Suspense Hooks Reference\n\n> **Note**: Suspense hooks are the recommended approach for data fetching in modern React applications (React 18+). They provide cleaner code, better loading state handling, and enable streaming SSR.\n\n## Table of Contents\n\n- [useSuspenseQuery Hook](#usesuspensequery-hook)\n- [useBackgroundQuery and useReadQuery](#usebackgroundquery-and-usereadquery)\n- [useLoadableQuery](#useloadablequery)\n- [createQueryPreloader](#createquerypreloader)\n- [useQueryRefHandlers](#usequeryrefhandlers)\n- [Distinguishing Queries with queryKey](#distinguishing-queries-with-querykey)\n- [Suspense Boundaries and Error Handling](#suspense-boundaries-and-error-handling)\n- [Transitions](#transitions)\n- [Avoiding Request Waterfalls](#avoiding-request-waterfalls)\n- [Fetch Policies](#fetch-policies)\n- [Streaming SSR or React Server Components](#streaming-ssr-or-react-server-components)\n- [Conditional Queries](#conditional-queries)\n\n## useSuspenseQuery Hook\n\nThe `useSuspenseQuery` hook is the Suspense-ready replacement for `useQuery`. It initiates a network request and causes the component calling it to suspend while the request is made. Unlike `useQuery`, it does not return `loading` states—these are handled by React's Suspense boundaries and error boundaries.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\nimport { GET_DOG } from \"./queries.generated\";\n\nfunction App() {\n return (\n Name: {data.dog.name}
;\n}\n```\n\n### Return Object\n\n```typescript\nconst {\n data, // Query result data\n dataState, // With default options: \"complete\" | \"streaming\"\n // With returnPartialData: also \"partial\"\n // With errorPolicy \"all\" or \"ignore\": also \"empty\"\n error, // ApolloError (only when errorPolicy is \"all\" or \"ignore\")\n networkStatus, // NetworkStatus.ready, NetworkStatus.loading, etc.\n client, // Apollo Client instance\n refetch, // Function to re-execute query\n fetchMore, // Function for pagination\n} = useSuspenseQuery(QUERY, options);\n```\n\n### Key Differences from useQuery\n\n- **No `loading` boolean**: Component suspends instead of returning `loading: true`\n- **Error handling**: With default `errorPolicy` (`none`), errors are thrown and caught by error boundaries. With `errorPolicy: \"all\"` or `\"ignore\"`, the `error` property is returned and `data` may be `undefined`.\n- **`data` availability**: With default `errorPolicy` (`none`), `data` is guaranteed to be present when the component renders. With `errorPolicy: \"all\"` or `\"ignore\"`, when `dataState` is `empty`, `data` may be `undefined`.\n- **Suspense boundaries**: Must wrap component with `Name: {data.dog.name}
\n Breed: {data.dog.breed}
\n \n );\n}\n```\n\n### Rendering Partial Data\n\nUse `returnPartialData` to render immediately with partial cache data instead of suspending. The component will still suspend if there is no data in the cache.\n\n```tsx\nfunction Dog({ id }: { id: string }) {\n const { data } = useSuspenseQuery(GET_DOG, {\n variables: { id },\n returnPartialData: true,\n });\n\n return (\n <>\n Name: {data.dog?.name ?? \"Unknown\"}
\n {data.dog?.breed && Breed: {data.dog.breed}
}\n \n );\n}\n```\n\n## useBackgroundQuery and useReadQuery\n\nUse `useBackgroundQuery` with `useReadQuery` to avoid request waterfalls by starting a query in a parent component and reading the result in a child component. This pattern enables the parent to start fetching data before the child component renders.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useBackgroundQuery, useReadQuery } from \"@apollo/client/react\";\n\nfunction Parent() {\n // Start fetching immediately\n const [queryRef] = useBackgroundQuery(GET_DOG, {\n variables: { id: \"3\" },\n });\n\n return (\n Name: {data.dog.name}
;\n}\n```\n\n### When to Use\n\n- **Avoiding waterfalls**: Start fetching data in a parent (preferably above a suspense boundary) before child components render\n- **Preloading data**: Begin fetching before the component that needs the data is ready\n- **Parallel queries**: Start multiple queries at once in a parent component\n\n### Return Values\n\n`useBackgroundQuery` returns a tuple:\n\n```typescript\nconst [\n queryRef, // QueryRef to pass to useReadQuery\n { refetch, fetchMore, subscribeToMore }, // Helper functions\n] = useBackgroundQuery(QUERY, options);\n```\n\n`useReadQuery` returns the query result:\n\n```typescript\nconst {\n data, // Query result data (always defined)\n dataState, // \"complete\" | \"streaming\" | \"partial\" | \"empty\"\n error, // ApolloError (if errorPolicy allows)\n networkStatus, // Detailed network state (1-8)\n} = useReadQuery(queryRef);\n```\n\n## useLoadableQuery\n\nUse `useLoadableQuery` to imperatively load a query in response to a user interaction (like a button click) instead of on component mount.\n\n### Basic Usage\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useLoadableQuery, useReadQuery } from \"@apollo/client/react\";\nimport { GET_GREETING } from \"./queries.generated\";\n\nfunction App() {\n const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);\n\n return (\n <>\n {data.greeting.message}
;\n}\n```\n\n### Return Values\n\n```typescript\nconst [\n loadQuery, // Function to load the query\n queryRef, // QueryRef (null until loadQuery is called)\n { refetch, fetchMore, subscribeToMore, reset }, // Helper functions\n] = useLoadableQuery(QUERY, options);\n```\n\n### When to Use\n\n- **User-triggered fetching**: Load data in response to user actions\n- **Lazy loading**: Defer data fetching until it's actually needed\n- **Progressive disclosure**: Load data for UI elements that may not be initially visible\n\n## createQueryPreloader\n\nThe `createQueryPreloader` function creates a `preloadQuery` function that can be used to initiate queries outside of React components. This is useful for preloading data before a component renders, such as in route loaders or event handlers.\n\n### Basic Usage\n\n```tsx\nimport { ApolloClient, InMemoryCache } from \"@apollo/client\";\nimport { createQueryPreloader } from \"@apollo/client/react\";\n\nconst client = new ApolloClient({\n uri: \"https://your-graphql-endpoint.com/graphql\",\n cache: new InMemoryCache(),\n});\n\n// Create a preload function\nexport const preloadQuery = createQueryPreloader(client);\n```\n\n### Using preloadQuery with Route Loaders\n\n> **Note**: This example applies to React Router in non-framework mode. For React Router framework mode, see [integration-react-router.md](./integration-react-router.md).\n\nUse the preload function with React Router's `loader` function to begin loading data during route transitions:\n\n```tsx\nimport { preloadQuery } from \"@/lib/apollo-client\";\nimport { GET_DOG } from \"./queries.generated\";\n\n// React Router loader function\nexport async function loader({ params }: { params: { id: string } }) {\n return preloadQuery({\n query: GET_DOG,\n variables: { id: params.id },\n });\n}\n\n// Route component\nexport default function DogRoute() {\n const queryRef = useLoaderData();\n\n return (\n \n
\n );\n}\n```\n\n### Preventing Route Transitions Until Query Loads\n\nUse `preloadQuery.toPromise(queryRef)` to prevent route transitions until the query finishes loading:\n\n```tsx\nexport async function loader({ params }: { params: { id: string } }) {\n const queryRef = preloadQuery({\n query: GET_DOG,\n variables: { id: params.id },\n });\n\n // Wait for the query to complete before transitioning\n return preloadQuery.toPromise(queryRef);\n}\n```\n\nWhen `preloadQuery.toPromise()` is used, the route transition waits for the query to complete, and the data renders immediately without showing a loading fallback.\n\n> **Note**: `preloadQuery.toPromise()` resolves with the `queryRef` itself (not the data) to encourage using `useReadQuery` for cache updates. If you need raw query data in your loader, use `client.query()` directly.\n\n### With Next.js Server Components\n\n> **Note**: For Next.js App Router, use the `PreloadQuery` component from `@apollo/client-integration-nextjs` instead. See [integration-nextjs.md](./integration-nextjs.md) for details.\n\n## useQueryRefHandlers\n\nThe `useQueryRefHandlers` hook provides access to `refetch` and `fetchMore` functions for queries initiated with `preloadQuery`, `useBackgroundQuery`, or `useLoadableQuery`. This is useful when you need to refetch or paginate data in components where the `queryRef` is passed through.\n\n> **Important:** Always call `useQueryRefHandlers` before `useReadQuery`. These two hooks interact with the same `queryRef`, and calling them in the wrong order could cause subtle bugs.\n\n### Basic Usage\n\n```tsx\nimport { useQueryRefHandlers } from \"@apollo/client/react\";\n\nfunction Breeds({ queryRef }: { queryRef: QueryRef{data.dog.name}
\nBreed: {data.dog.breed}
\n\n {\n startTransition(() => {\n refetch();\n });\n }}\n >\n {isPending ? \"Refetching...\" : \"Refetch breeds\"}\n \n
\n );\n}\n```\n\n### With Pagination\n\nUse `fetchMore` to implement pagination:\n\n```tsx\nfunction Posts({ queryRef }: { queryRef: QueryRef- \n {data.breeds.map((breed) => (\n
- {breed.name} \n ))}\n
\n {\n startTransition(() => {\n fetchMore({\n variables: {\n offset: data.posts.length,\n },\n });\n });\n }}\n >\n {isPending ? \"Loading...\" : \"Load more\"}\n \n
\n );\n}\n```\n\n### When to Use\n\n- **Preloaded queries**: Access refetch/fetchMore for queries initiated with `preloadQuery`\n- **Background queries**: Use in child components receiving `queryRef` from `useBackgroundQuery`\n- **Loadable queries**: Refetch or paginate queries initiated with `useLoadableQuery`\n- **React transitions**: Integrate with transitions to avoid showing loading fallbacks during refetches\n\n## Distinguishing Queries with queryKey\n\nApollo Client uses the combination of `query` and `variables` to uniquely identify each query. When multiple components use the same `query` and `variables`, they share the same identity and suspend at the same time, regardless of which component initiates the request.\n\nUse the `queryKey` option to ensure each hook has a unique identity:\n\n```tsx\nfunction UserProfile() {\n // First query with unique key\n const { data: userData } = useSuspenseQuery(GET_USER, {\n variables: { id: \"1\" },\n queryKey: [\"user-profile\"],\n });\n\n // Second query with same query and variables but different key\n const { data: userPreview } = useSuspenseQuery(GET_USER, {\n variables: { id: \"1\" },\n queryKey: [\"user-preview\"],\n });\n\n return (\n - \n {data.posts.map((post) => (\n
- {post.title} \n ))}\n
\n
\n );\n}\n```\n\n### When to Use\n\n- **Multiple instances**: When rendering multiple components that use the same query and variables\n- **Preventing shared suspension**: When you want independent control over when each query suspends\n- **Separate cache entries**: When you need to maintain separate cache states for the same query\n\n> **Note**: Each item in the `queryKey` array must be a stable identifier to prevent infinite fetches.\n\n## Suspense Boundaries and Error Handling\n\n### Suspense Boundaries\n\nWrap components that use Suspense hooks with `\n
\n )}\n >\n Something went wrong
\n{error.message}
\nName: {data?.dog?.name ?? \"Unknown\"}
\n {error && Warning: {error.message}
}\n \n );\n}\n```\n\n## Transitions\n\nUse React transitions to avoid showing loading UI when updating state. Transitions keep the previous UI visible while new data is fetching.\n\n### Using startTransition\n\n```tsx\nimport { useState, Suspense, startTransition } from \"react\";\n\nfunction DogSelector() {\n const { data } = useSuspenseQuery(GET_DOGS);\n const [selectedDog, setSelectedDog] = useState(data.dogs[0].id);\n\n return (\n <>\n User: {data.user.name}
;\n}\n\nfunction PostsList({ queryRef }: { queryRef: QueryRef- \n {data.posts.map((post) => (\n
- {post.title} \n ))}\n
Select a user
;\n }\n\n returnSelect a user
;\n }\n\n return (\n- {data?.users.map((user) =>
- {user.name} )}
{data.user.name}
;\n\n// Or use optional chaining\nreturn {data?.user?.name}
;\n```\n\n\n# TypeScript Code Generation\n\nThis guide covers setting up GraphQL Code Generator for type-safe Apollo Client usage with TypeScript.\n\n## Installation\n\n```bash\nnpm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node\n```\n\n## Configuration\n\nCreate a `codegen.ts` file in your project root:\n\n```typescript\n// codegen.ts\nimport { CodegenConfig } from \"@graphql-codegen/cli\";\n\nconst config: CodegenConfig = {\n overwrite: true,\n schema: \"{data?.user.name}
;\n}\n```\n\n## Important Notes\n\n- The typed-document-node plugin might have a bundle size tradeoff but can prevent inconsistencies and is best suited for usage with LLMs, so it is recommended for most applications.\n- See the [GraphQL Code Generator documentation](https://www.apollographql.com/docs/react/development-testing/graphql-codegen#recommended-starter-configuration) for other recommended configuration patterns if required.\n- Apollo Client hooks automatically infer types from `TypedDocumentNode` - never use manual generics like `useQueryLoading...
;\n if (error) returnError: {error.message}
;\n\n // TypeScript note: for stricter type narrowing, you can also check `dataState === \"complete\"` before accessing data\n return{data?.user.name}
;\n}\n```\n\n### Basic Mutation\n\n```tsx\nimport { gql } from \"@apollo/client\";\nimport { useMutation } from \"@apollo/client/react\";\n\nconst CREATE_USER = gql`\n mutation CreateUser($input: CreateUserInput!) {\n createUser(input: $input) {\n id\n name\n }\n }\n`;\n\nfunction CreateUserForm() {\n const [createUser, { loading, error }] = useMutation(CREATE_USER);\n\n const handleSubmit = async (name: string) => {\n await createUser({ variables: { input: { name } } });\n };\n\n return ;\n}\n```\n\n### Suspense Query\n\n```tsx\nimport { Suspense } from \"react\";\nimport { useSuspenseQuery } from \"@apollo/client/react\";\n\nfunction UserProfile({ userId }: { userId: string }) {\n const { data } = useSuspenseQuery(GET_USER, {\n variables: { id: userId },\n });\n\n return {data.user.name}
;\n}\n\nfunction App() {\n return (\n