docs: add instructions for enabling data masking types in Apollo Client

Author: nickmessing

packages/docs/data/data-masking.md

@@ -3,7 +3,7 @@
 Data masking prevents components from accessing GraphQL fields they didn't explicitly request. This creates loosely coupled components that are more resistant to breaking changes.
 
 ::: tip Recommended: Use with GraphQL Codegen
-Data masking works best with [GraphQL Codegen](https://the-guild.dev/graphql/codegen) for type-safe masked types. See the [TypeScript page](/data/typescript) for setup instructions.
+Data masking works best with [GraphQL Codegen](https://the-guild.dev/graphql/codegen) for type-safe masked types. See the [TypeScript page](/data/typescript) for setup instructions, including the required [type augmentation](/data/typescript#enabling-data-masking-types) to make masked types work correctly.
 :::
 
 ## The Problem
@@ -208,7 +208,14 @@ const client = new ApolloClient({
 })
 ```
 
-### 3. Refactor Components
+### 3. Configure TypeScript (if applicable)
+
+If you're using TypeScript with GraphQL Codegen, you need to:
+
+1. Update your codegen config to generate masked types (see [TypeScript setup](/data/typescript#configuration))
+2. Create the type augmentation file (see [Enabling Data Masking Types](/data/typescript#enabling-data-masking-types))
+
+### 4. Refactor Components
 
 Gradually refactor components to use `useFragment` and remove `@unmask` directives:
 

packages/docs/data/typescript.md

@@ -179,6 +179,32 @@ The `graphql()` function:
 - Returns a `TypedDocumentNode` with full type inference
 - Automatically includes fragment definitions
 
+### Enabling Data Masking Types
+
+By default, Apollo Client doesn't modify operation types regardless of whether they are masked or unmasked. To use GraphQL Codegen's masking format with your operation types, you need to tell Apollo Client to use the associated GraphQL Codegen masking types.
+
+Create a TypeScript declaration file (e.g., `apollo-client.d.ts`) in your project:
+
+```ts
+// This import is necessary to ensure all Apollo Client imports
+// are still available to the rest of the application.
+import '@apollo/client'
+import type { GraphQLCodegenDataMasking } from '@apollo/client/masking'
+
+declare module '@apollo/client' {
+  interface TypeOverrides extends GraphQLCodegenDataMasking.TypeOverrides {}
+}
+```
+
+This extends Apollo Client's `TypeOverrides` interface with the GraphQL Codegen data masking types, ensuring that:
+- Masked types don't include fields from fragment spreads
+- The `@unmask` directive properly unmasks types
+- `FragmentType` works correctly for type-safe fragment props
+
+::: tip
+Make sure TypeScript can find this declaration file. It should be in a location covered by your `tsconfig.json`'s `include` patterns.
+:::
+
 ### Type-Safe Fragments
 
 Use `FragmentType` from `@apollo/client` to type component props that receive fragment data: