Updated apollo migration docs with newest config options (#10724)

* updated apollo migration docs

* better comments

* better comments

* Format

---------

Co-authored-by: Igor Kusakov <igor@kusakov.com>
Co-authored-by: Eddy Nguyen <github@eddeee888.me>

Author: 3 people

website/src/pages/docs/migration/apollo-tooling.mdx

@@ -93,14 +93,17 @@ import type { CodegenConfig } from '@graphql-codegen/cli'
 const config: CodegenConfig = {
   schema: './schema.graphql',
   documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
+  externalDocuments: [
+    '../other-package/src/**/*.{ts,tsx}',
+    '!../other-package/src/**/__generated__/**'
+  ],
   generates: {
     './src/': {
       preset: 'near-operation-file',
       presetConfig: {
         extension: '.ts',
         folder: '__generated__',
-        filePerOperation: true,
-        inGeneratesOnly: true
+        filePerOperation: true
       },
       plugins: ['typescript-operations'],
       config: {
@@ -154,14 +157,17 @@ import type { CodegenConfig } from '@graphql-codegen/cli'
 const config: CodegenConfig = {
   schema: './schema.graphql',
   documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
+  externalDocuments: [
+    '../other-package/src/**/*.{ts,tsx}',
+    '!../other-package/src/**/__generated__/**'
+  ],
   generates: {
     './src/': {
       preset: 'near-operation-file',
       presetConfig: {
         extension: '.ts', // Extension for generated files
         folder: '__generated__', // Generated files go into __generated__/ subfolder
-        filePerOperation: true, // Generate type files per-operation (not per-component)
-        inGeneratesOnly: true // Only generate files defined in `generates` scan paths (don't generate for all `documents`)
+        filePerOperation: true // Generate type files per-operation (not per-component)
       },
       plugins: ['typescript-operations']
     }
@@ -196,14 +202,17 @@ configuration option:
 const config: CodegenConfig = {
   schema: './schema.graphql',
   documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
+  externalDocuments: [
+    '../other-package/src/**/*.{ts,tsx}',
+    '!../other-package/src/**/__generated__/**'
+  ],
   generates: {
     './src/': {
       preset: 'near-operation-file',
       presetConfig: {
         extension: '.ts',
         folder: '__generated__',
-        filePerOperation: true,
-        inGeneratesOnly: true
+        filePerOperation: true
       },
       plugins: ['typescript-operations'],
       config: {
@@ -239,14 +248,17 @@ declarations matching Apollo Tooling's output, set `enumType: 'native'`:
 const config: CodegenConfig = {
   schema: './schema.graphql',
   documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
+  externalDocuments: [
+    '../other-package/src/**/*.{ts,tsx}',
+    '!../other-package/src/**/__generated__/**'
+  ],
   generates: {
     './src/': {
       preset: 'near-operation-file',
       presetConfig: {
         extension: '.ts',
         folder: '__generated__',
-        filePerOperation: true,
-        inGeneratesOnly: true
+        filePerOperation: true
       },
       plugins: ['typescript-operations'],
       config: {
@@ -284,16 +296,20 @@ import type { CodegenConfig } from '@graphql-codegen/cli'
 const config: CodegenConfig = {
   schema: './schema.graphql',
   documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
+  // `externalDocuments` are read-only documents that are loaded but do not generate output.
+  // They are used to include fragments from another package in a monorepo without generating unnecessary files.
+  externalDocuments: [
+    '../other-package/src/**/*.{ts,tsx}',
+    '!../other-package/src/**/__generated__/**'
+  ],
   generates: {
     './src/': {
       preset: 'near-operation-file',
       presetConfig: {
         extension: '.ts',
         folder: '__generated__',
         // Generate type files per-operation (not per-component)
-        filePerOperation: true,
-        // Only generate files defined in `generates` scan paths (don't generate for all `documents`)
-        inGeneratesOnly: true
+        filePerOperation: true
       },
       plugins: ['typescript-operations'],
       config: {
@@ -329,17 +345,17 @@ export default config
 The setup above closely mimics Apollo Tooling but isn’t an exact match. The following items may
 require manual fixes:
 
-1. Nested field types naming.
+#### 1. Nested field types naming.
 
-In very rare cases, the names generated by GraphQL Codegen don’t match Apollo Tooling’s. Update
-these cases manually.
+In very rare cases, the field names generated by GraphQL Codegen don’t match Apollo Tooling’s.
+Update these cases manually.
 
-2. Enum file location.
+#### 2. Enum file location.
 
 Occasionally, GraphQL Codegen places enums in a different file then Apollo Tooling. If an enum is
 missing, check nearby generated files and adjust your imports accordingly.
 
-3. `is possibly null` and `has any type` typecheck bugs.
+#### 3. `is possibly null` and `has any type` typecheck bugs.
 
 These bugs has to be fixed.
 
@@ -351,30 +367,33 @@ For `is possibly null` bug, asserting for not null or adding `!` will fix most c
 
 For `has any type` bug - a proper type needs to be determined.
 
-4. Mismatch between `Type | null` and `Type | null | undefined`.
+#### 4. Mismatch between `Type | null` and `Type | null | undefined`.
 
 Experiment with the following configuration options to keep your codebase changes to a minimum:
 
-```
-  maybeValue: defaults to 'T | null', set to 'T | null | undefined' if necessary
-  inputMaybeValue: defaults to 'Maybe<T>', set to 'T | null | undefined' if necessary
-  avoidOptionals: Replaces ? optional modifier with explicit Maybe<T>. Supports granular control via object form.
-  allowUndefinedQueryVariables: Adds | undefined to Query operation variable types (not Mutation/Subscription)
-  optionalResolveType: Makes __resolveType optional (__resolveType?) in resolver types.
-  nullability:  When errorHandlingClient: true, adjusts nullability for fields marked with @semanticNonNull directive (requires graphql-sock).
-```
+- **maybeValue**: defaults to `T | null`, set to `T | null | undefined` if necessary
+- **inputMaybeValue**: defaults to `Maybe<T>`, set to `T | null | undefined` if necessary
+- **avoidOptionals**: Replaces ? optional modifier with explicit `Maybe<T>`. Supports granular
+  control via object form.
+- **allowUndefinedQueryVariables**: Adds | undefined to Query operation variable types (not
+  Mutation/Subscription)
+- **optionalResolveType**: Makes `__resolveType` optional (`__resolveType?`) in resolver types.
+- **nullability**: When `errorHandlingClient: true`, adjusts nullability for fields marked with
+  `@semanticNonNull` directive (requires `graphql-sock`).
 
-5. Extra `__typename` present, or required `__typename` missing.
+#### 5. Extra `__typename` present, or required `__typename` missing.
 
 Experiment with the following configuration options to keep your codebase changes to a minimum:
 
-```
-  skipTypename: prevents adding __typename to generated types unless explicitly in the selection set.
-  skipTypeNameForRoot: skips __typename specifically for root types (Query, Mutation, Subscription). Ignored if __typename is explicitly in the selection set
-  nonOptionalTypename: always adds __typename and makes it a required (non-optional) field.
-  addTypenameToSelectionSets: injects __typename directly into the generated document node selection sets.
-  resolversNonOptionalTypename: makes __typename non-optional in resolver mappings without affecting base types. Supports granular control via object form.
-```
+- **skipTypename**: prevents adding `__typename` to generated types unless explicitly in the
+  selection set.
+- **skipTypeNameForRoot**: skips `__typename` specifically for root types (Query, Mutation,
+  Subscription). Ignored if `__typename` is explicitly in the selection set
+- **nonOptionalTypename**: always adds `__typename` and makes it a required (non-optional) field.
+- **addTypenameToSelectionSets**: injects `__typename` directly into the generated document node
+  selection sets.
+- **resolversNonOptionalTypename**: makes `__typename` non-optional in resolver mappings without
+  affecting base types. Supports granular control via object form.
 
 ## Further reading