@apollo/client 4.1.7 → 4.1.9

package/skills/apollo-client/references/fragments.md

@@ -0,0 +1,804 @@
+# Fragments Reference
+
+GraphQL 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.
+
+## Table of Contents
+
+- [What Are Fragments](#what-are-fragments)
+- [Basic Fragment Syntax](#basic-fragment-syntax)
+- [Fragment Colocation](#fragment-colocation)
+- [Fragment Reading Hooks](#fragment-reading-hooks)
+- [Data Masking](#data-masking)
+- [Fragment Registry](#fragment-registry)
+- [TypeScript Integration](#typescript-integration)
+- [Best Practices](#best-practices)
+
+## What Are Fragments
+
+A 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 (`...`).
+
+In Apollo Client, fragments serve a specific purpose:
+
+**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.
+
+Fragments enable:
+
+1. **Component colocation**: Define the exact data requirements for a component alongside the component code
+2. **Independent evolution**: Change a component's data needs without affecting other components
+3. **Code organization**: Compose fragments together to build complete queries that mirror your component hierarchy
+
+## Basic Fragment Syntax
+
+### Defining a Fragment
+
+```typescript
+import { gql } from "@apollo/client";
+
+const USER_FRAGMENT = gql`
+  fragment UserFields on User {
+    id
+    name
+    email
+    avatarUrl
+  }
+`;
+```
+
+Every fragment includes:
+
+- A unique name (`UserFields`)
+- The type it operates on (`User`)
+- The fields to select
+
+### Using Fragments in Queries
+
+Include fragments in queries using the spread operator:
+
+```typescript
+const GET_USER = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      ...UserFields
+    }
+  }
+
+  ${USER_FRAGMENT}
+`;
+```
+
+When 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.
+
+## Fragment Colocation
+
+Fragment 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.
+
+### Why Colocate Fragments
+
+- **Locality**: Data requirements live next to the code that uses them
+- **Maintainability**: Changes to component UI and data needs happen together
+- **Type safety**: TypeScript can infer exact types from colocated fragments
+- **Independence**: Components can evolve their data requirements without affecting other components
+
+### Colocation Pattern
+
+The recommended pattern for colocating fragments with components:
+
+```tsx
+import { gql, FragmentType } from "@apollo/client";
+import { useSuspenseFragment } from "@apollo/client/react";
+
+// Fragment definition
+// This will be picked up by Codegen to create `UserCard_UserFragmentDoc` in `./fragments.generated.ts`.
+// As that generated fragment document is correctly typed, we use that in the code going forward.
+// This fragment will never be consumed in runtime code, so it is wrapped in `if (false)` so the bundler can omit it when bundling.
+if (false) {
+  gql`
+    fragment UserCard_user on User {
+      id
+      name
+      email
+      avatarUrl
+    }
+  `;
+}
+
+// This has been created from above fragment definition by CodeGen and is a correctly typed `TypedDocumentNode`
+import { UserCard_UserFragmentDoc } from "./fragments.generated.ts";
+
+// Component receives the (partially masked) parent object
+export function UserCard({
+  user,
+}: {
+  user: FragmentType<typeof UserCard_UserFragmentDoc>;
+}) {
+  // Creates a subscription to the fragment in the cache
+  const { data } = useSuspenseFragment({
+    fragment: UserCard_UserFragmentDoc,
+    fragmentName: "UserCard_user",
+    from: user,
+  });
+
+  return (
+    <div>
+      <img src={data.avatarUrl} alt={data.name} />
+      <h2>{data.name}</h2>
+      <p>{data.email}</p>
+    </div>
+  );
+}
+```
+
+### Naming Convention
+
+A suggested naming pattern for fragments follows this convention:
+
+```text
+{ComponentName}_{propName}
+```
+
+Where `propName` is the name of the prop the component receives containing the fragment data.
+
+Examples:
+
+- `UserCard_user` - Fragment for the `user` prop in the UserCard component
+- `PostList_posts` - Fragment for the `posts` prop in the PostList component
+- `CommentItem_comment` - Fragment for the `comment` prop in the CommentItem component
+
+This convention makes it clear which component owns which fragment. However, you can choose a different naming convention based on your project's needs.
+
+**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.
+
+### Composing Fragments
+
+Parent components compose child fragments to build complete queries:
+
+```tsx
+// Child component
+import { gql } from "@apollo/client";
+
+if (false) {
+  gql`
+    fragment UserAvatar_user on User {
+      id
+      avatarUrl
+      name
+    }
+  `;
+}
+
+// Parent component composes child fragments
+if (false) {
+  gql`
+    fragment UserProfile_user on User {
+      id
+      name
+      email
+      bio
+      ...UserAvatar_user
+    }
+  `;
+}
+
+// Page-level query composes all fragments
+if (false) {
+  gql`
+    query UserProfilePage($id: ID!) {
+      user(id: $id) {
+        ...UserProfile_user
+      }
+    }
+  `;
+}
+```
+
+This creates a hierarchy that mirrors your component tree.
+
+## Fragment Reading Hooks
+
+Apollo 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.
+
+### useSuspenseFragment
+
+For components using Suspense and concurrent features:
+
+```tsx
+import { useSuspenseFragment } from "@apollo/client/react";
+import { FragmentType } from "@apollo/client";
+import { UserCard_UserFragmentDoc } from "./fragments.generated";
+
+function UserCard({
+  user,
+}: {
+  user: FragmentType<typeof UserCard_UserFragmentDoc>;
+}) {
+  const { data } = useSuspenseFragment({
+    fragment: UserCard_UserFragmentDoc,
+    fragmentName: "UserCard_user",
+    from: user,
+  });
+
+  return <div>{data.name}</div>;
+}
+```
+
+### useFragment
+
+For components not using Suspense:
+
+```tsx
+import { useFragment } from "@apollo/client/react";
+import { FragmentType } from "@apollo/client";
+import { UserCard_UserFragmentDoc } from "./fragments.generated";
+
+function UserCard({
+  user,
+}: {
+  user: FragmentType<typeof UserCard_UserFragmentDoc>;
+}) {
+  const { data, complete } = useFragment({
+    fragment: UserCard_UserFragmentDoc,
+    fragmentName: "UserCard_user",
+    from: user,
+  });
+
+  if (!complete) {
+    return <div>Loading...</div>;
+  }
+
+  return <div>{data.name}</div>;
+}
+```
+
+The `complete` field indicates whether all fragment data is available in the cache.
+
+### Hook Options
+
+Both hooks accept these options:
+
+```typescript
+{
+  // The fragment document (required)
+  fragment: TypedDocumentNode,
+
+  // The fragment name (optional in most cases)
+  // Only required if the fragment document contains multiple definitions
+  fragmentName?: string,
+
+  // The source data containing the fragment (required)
+  // Can be a single object or an array of objects
+  from: FragmentType<typeof fragment> | Array<FragmentType<typeof fragment>>,
+
+  // Variables for the fragment (optional)
+  variables?: Variables,
+}
+```
+
+When `from` is an array, the hook returns an array of results, allowing you to read fragments from multiple objects efficiently. **Note**: Array support for the `from` parameter was added in Apollo Client 4.1.0.
+
+## Data Masking
+
+Data masking is a feature that prevents components from accessing data they didn't explicitly request through their fragments. This enforces proper data boundaries and prevents over-rendering.
+
+### Enabling Data Masking
+
+Enable data masking when creating your Apollo Client:
+
+```typescript
+import { ApolloClient, InMemoryCache } from "@apollo/client";
+
+const client = new ApolloClient({
+  cache: new InMemoryCache(),
+  dataMasking: true, // Enable data masking
+});
+```
+
+### How Data Masking Works
+
+With data masking enabled:
+
+1. Fragments return opaque `FragmentType` objects
+2. Components must use `useFragment` or `useSuspenseFragment` to unmask data
+3. Components can only access fields defined in their own fragments
+4. TypeScript enforces these boundaries at compile time
+
+Without data masking:
+
+```tsx
+// ❌ Without data masking - component can access any data from parent
+function UserCard({ user }: { user: User }) {
+  // Can access any User field, even if not in fragment
+  return <div>{user.privateData}</div>;
+}
+```
+
+With data masking:
+
+```tsx
+// ✅ With data masking - component can only access its fragment data
+import { UserCard_UserFragmentDoc } from "./fragments.generated";
+
+function UserCard({
+  user,
+}: {
+  user: FragmentType<typeof UserCard_UserFragmentDoc>;
+}) {
+  const { data } = useSuspenseFragment({
+    fragment: UserCard_UserFragmentDoc,
+    from: user,
+  });
+
+  // TypeScript error: 'privateData' doesn't exist on fragment type
+  // return <div>{data.privateData}</div>;
+
+  // Only fields from the fragment are accessible
+  return <div>{data.name}</div>;
+}
+```
+
+### Benefits of Data Masking
+
+- **Prevents over-rendering**: Components only re-render when their specific data changes
+- **Enforces boundaries**: Components can't accidentally depend on data they don't own
+- **Better refactoring**: Safe to modify parent queries without breaking child components
+- **Type safety**: TypeScript catches attempts to access unavailable fields
+
+## Fragment Registry
+
+The 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.
+
+**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**.
+
+### Creating a Fragment Registry
+
+```typescript
+import { ApolloClient, InMemoryCache } from "@apollo/client";
+import { createFragmentRegistry } from "@apollo/client/cache";
+
+export const fragmentRegistry = createFragmentRegistry();
+
+const client = new ApolloClient({
+  cache: new InMemoryCache({
+    fragments: fragmentRegistry,
+  }),
+});
+```
+
+### Registering Fragments
+
+Register fragments after defining them:
+
+```typescript
+import { gql } from "@apollo/client";
+import { fragmentRegistry } from "./apollo/client";
+
+const USER_FRAGMENT = gql`
+  fragment UserFields on User {
+    id
+    name
+    email
+  }
+`;
+
+fragmentRegistry.register(USER_FRAGMENT);
+```
+
+With colocated fragments:
+
+```tsx
+import { fragmentRegistry } from "@/apollo/client";
+import { UserCard_UserFragmentDoc } from "./fragments.generated";
+
+// Register the fragment globally
+fragmentRegistry.register(UserCard_UserFragmentDoc);
+```
+
+### Using Registered Fragments
+
+Once registered, fragments can be referenced by name in queries without explicit imports:
+
+```tsx
+// Fragment is available by name because it's registered
+const GET_USER = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      ...UserCard_user
+    }
+  }
+`;
+```
+
+### Approaches for Fragment Composition
+
+There are three approaches to make child fragments available in parent queries:
+
+1. **GraphQL Code Generator inlining** (Recommended): CodeGen automatically inlines fragments by name. No manual work needed—just reference fragments by name in your queries.
+
+2. **Fragment Registry**: Manually register fragments to make them available by name. Useful for runtime scenarios where CodeGen isn't available.
+
+3. **Manual interpolation**: Explicitly import and interpolate child fragments into parent fragments:
+
+   ```typescript
+   import { CHILD_FRAGMENT } from "./ChildComponent";
+
+   const PARENT_FRAGMENT = gql`
+     fragment Parent_data on Data {
+       field
+       ...Child_data
+     }
+     ${CHILD_FRAGMENT}
+   `;
+   ```
+
+### Pros and Cons
+
+**GraphQL Code Generator inlining**:
+
+- ✅ Less work: Automatic, no manual registration needed
+- ❌ Larger bundle: Fragments are inlined into every query that uses them
+
+**Fragment Registry**:
+
+- ✅ Smaller bundle: Fragments are registered once, referenced by name
+- ❌ More work: Requires manual registration of each fragment
+- ❌ May cause issues with lazy-loaded modules if the module is not loaded before the query is executed
+- ✅ Best for deeply nested component trees where bundle size matters
+
+**Manual interpolation**:
+
+- ❌ Most work: Manual imports and interpolation required
+- ✅ Explicit: Clear fragment dependencies in code
+
+### Recommendation
+
+For 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.
+
+## TypeScript Integration
+
+Apollo Client provides strong TypeScript support for fragments through GraphQL Code Generator.
+
+### Generated Types
+
+GraphQL Code Generator produces typed fragment documents:
+
+```typescript
+// Generated file: fragments.generated.ts
+export type UserCard_UserFragment = {
+  __typename: "User";
+  id: string;
+  name: string;
+  email: string;
+  avatarUrl: string;
+} & { " $fragmentName"?: "UserCard_UserFragment" };
+
+export const UserCard_UserFragmentDoc: TypedDocumentNode<
+  UserCard_UserFragment,
+  never
+>;
+```
+
+### Type-Safe Fragment Usage
+
+Use `FragmentType` to accept masked fragment data:
+
+```tsx
+import { FragmentType } from "@apollo/client";
+import { UserCard_UserFragmentDoc } from "./fragments.generated";
+
+function UserCard({
+  user,
+}: {
+  user: FragmentType<typeof UserCard_UserFragmentDoc>;
+}) {
+  const { data } = useSuspenseFragment({
+    fragment: UserCard_UserFragmentDoc,
+    from: user,
+  });
+
+  // 'data' is fully typed as UserCard_UserFragment
+  return <div>{data.name}</div>;
+}
+```
+
+### Fragment Type Inference
+
+TypeScript infers types from fragment documents automatically:
+
+```tsx
+import { UserCard_UserFragmentDoc } from "./fragments.generated";
+
+// Types are inferred from the fragment
+const { data } = useSuspenseFragment({
+  fragment: UserCard_UserFragmentDoc,
+  from: user,
+});
+
+// data.name is string
+// data.email is string
+// data.nonExistentField is a TypeScript error
+```
+
+### Parent-Child Type Safety
+
+When passing fragment data from parent to child:
+
+```tsx
+// Parent query
+const { data } = useSuspenseQuery(GET_USER);
+
+// TypeScript ensures the query includes UserCard_user fragment
+// before allowing it to be passed to UserCard
+<UserCard user={data.user} />;
+```
+
+## Best Practices
+
+### Prefer Colocation Over Reuse
+
+**Fragments are for colocation, not reuse.** Each component should declare its data needs in a dedicated fragment, even if multiple components currently need the same fields.
+
+Sharing fragments between components just because they happen to need the same fields today creates artificial dependencies. When one component's requirements change, the shared fragment must be updated, causing all components using it to over-fetch data they don't need.
+
+```tsx
+// ✅ Good: Each component has its own fragment
+if (false) {
+  gql`
+    fragment UserCard_user on User {
+      id
+      name
+      email
+      avatarUrl
+    }
+  `;
+
+  gql`
+    fragment UserListItem_user on User {
+      id
+      name
+      email
+    }
+  `;
+}
+
+// If UserCard later needs 'bio', only UserCard_user changes
+// UserListItem doesn't over-fetch 'bio'
+```
+
+```tsx
+// ❌ Avoid: Sharing a generic fragment across components
+const COMMON_USER_FIELDS = gql`
+  fragment CommonUserFields on User {
+    id
+    name
+    email
+  }
+`;
+
+// UserCard and UserListItem both use CommonUserFields
+// When UserCard needs 'bio', adding it to CommonUserFields
+// causes UserListItem to over-fetch unnecessarily
+```
+
+This independence allows each component to evolve its data requirements without affecting unrelated parts of your application.
+
+### One Query Per Page
+
+Compose all page data requirements into a single query at the page level:
+
+```tsx
+// ✅ Good: Single page-level query
+if (false) {
+  gql`
+    query UserProfilePage($id: ID!) {
+      user(id: $id) {
+        ...UserHeader_user
+        ...UserPosts_user
+        ...UserFriends_user
+      }
+    }
+  `;
+}
+```
+
+```tsx
+// ❌ Avoid: Multiple queries in different components
+function UserProfile() {
+  const { data: userData } = useQuery(GET_USER);
+  const { data: postsData } = useQuery(GET_USER_POSTS);
+  const { data: friendsData } = useQuery(GET_USER_FRIENDS);
+  // ...
+}
+```
+
+### Use Fragment-Reading Hooks in Components
+
+Non-page components should use `useFragment` or `useSuspenseFragment`:
+
+```tsx
+// ✅ Good: Component reads fragment data
+import { FragmentType } from "@apollo/client";
+import { useSuspenseFragment } from "@apollo/client/react";
+import { UserCard_UserFragmentDoc } from "./fragments.generated";
+
+function UserCard({
+  user,
+}: {
+  user: FragmentType<typeof UserCard_UserFragmentDoc>;
+}) {
+  const { data } = useSuspenseFragment({
+    fragment: UserCard_UserFragmentDoc,
+    from: user,
+  });
+  return <div>{data.name}</div>;
+}
+```
+
+```tsx
+// ❌ Avoid: Component uses query hook
+function UserCard({ userId }: { userId: string }) {
+  const { data } = useQuery(GET_USER, { variables: { id: userId } });
+  return <div>{data.user.name}</div>;
+}
+```
+
+### Request Only Required Fields
+
+Keep fragments minimal and only request fields the component actually uses:
+
+```tsx
+// ✅ Good: Only necessary fields
+if (false) {
+  gql`
+    fragment UserListItem_user on User {
+      id
+      name
+    }
+  `;
+}
+```
+
+```tsx
+// ❌ Avoid: Requesting unused fields
+if (false) {
+  gql`
+    fragment UserListItem_user on User {
+      id
+      name
+      email
+      bio
+      friends {
+        id
+        name
+      }
+      posts {
+        id
+        title
+      }
+    }
+  `;
+}
+```
+
+### Use @defer for Below-the-Fold Content
+
+The `@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.
+
+Defer slow fields that aren't immediately visible:
+
+```tsx
+if (false) {
+  gql`
+    query ProductPage($id: ID!) {
+      product(id: $id) {
+        id
+        name
+        price
+        ...ProductReviews_product @defer
+      }
+    }
+  `;
+}
+```
+
+This allows the page to render quickly while reviews load in the background.
+
+### Handle Client-Only Fields
+
+Use the `@client` directive for fields resolved locally:
+
+```tsx
+if (false) {
+  gql`
+    fragment TodoItem_todo on Todo {
+      id
+      text
+      completed
+      isSelected @client
+    }
+  `;
+}
+```
+
+### Enable Data Masking for New Applications
+
+Always enable data masking in new applications:
+
+```typescript
+const client = new ApolloClient({
+  cache: new InMemoryCache(),
+  dataMasking: true,
+});
+```
+
+This enforces proper boundaries from the start and prevents accidental coupling between components.
+
+## Apollo Client Data Masking vs GraphQL-Codegen Fragment Masking
+
+Apollo Client's data masking and GraphQL Code Generator's fragment masking are different features that serve different purposes:
+
+### GraphQL-Codegen Fragment Masking
+
+GraphQL Code Generator's fragment masking (when using the client preset) is a **type-level** feature:
+
+- Masks data only at the TypeScript type level
+- The actual runtime data remains fully accessible on the object
+- Using their `useFragment` hook simply "unmasks" the data on a type level
+- Does not prevent accidental access to data at runtime
+- Parent components receive all data and pass it down
+- This means the parent component has to be subscribed to all data
+
+### Apollo Client Data Masking
+
+Apollo Client's data masking is a **runtime** feature with significant performance benefits:
+
+- Removes data at the runtime level, not just the type level
+- The `useFragment` and `useSuspenseFragment` hooks create cache subscriptions
+- Parent objects are sparse and only contain unmasked data
+- Prevents accidental access to data that should be masked
+
+### Key Benefits of Apollo Client Data Masking
+
+**1. No Accidental Data Access**
+
+With 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.
+
+**2. Fewer Re-renders**
+
+Apollo Client's approach creates more efficient subscriptions:
+
+- **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.
+- **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.
+
+### Example
+
+```tsx
+import { FragmentType } from "@apollo/client";
+import { useSuspenseQuery, useSuspenseFragment } from "@apollo/client/react";
+import { UserCard_UserFragmentDoc } from "./fragments.generated";
+
+function ParentComponent() {
+  const { data } = useSuspenseQuery(GET_USER);
+
+  // With Apollo Client data masking:
+  // - data.user only contains unmasked fields
+  // - Parent doesn't re-render when child-specific fields change
+
+  return <UserCard user={data.user} />;
+}
+
+function UserCard({
+  user,
+}: {
+  user: FragmentType<typeof UserCard_UserFragmentDoc>;
+}) {
+  // Creates a cache subscription specifically for UserCard_user fields
+  const { data } = useSuspenseFragment({
+    fragment: UserCard_UserFragmentDoc,
+    from: user,
+  });
+
+  // Only this component re-renders when these fields change
+  return <div>{data.name}</div>;
+}
+```
+
+This granular subscription approach improves performance in large applications with deeply nested component trees.