More documentation for migrating from Apollo Tooling to GraphQL Codegen (#10638)

* apollo-tooling migration docs updated

* prettier

* fix prettier bug

---------

Co-authored-by: Igor Kusakov <[email protected]>
Co-authored-by: Eddy Nguyen <[email protected]>

Author: 3 people

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

@@ -77,24 +77,37 @@ apollo client:codegen --target=typescript --outputFlat src/__generated__/types.t
 </Tabs.Tab>
 
 <Tabs.Tab>
+
 ```ts filename="codegen.ts"
 import type { CodegenConfig } from '@graphql-codegen/cli'
 
 const config: CodegenConfig = {
-schema: './schema.graphql',
-documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
-generates: {
-'./src/': {
-preset: 'near-operation-file',
-presetConfig: {
-extension: '.ts',
-folder: '**generated**',
-filePerOperation: true,
-inGeneratesOnly: true,
-},
-plugins: ['typescript-operations'],
-},
-},
+  schema: './schema.graphql',
+  documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
+  generates: {
+    './src/': {
+      preset: 'near-operation-file',
+      presetConfig: {
+        extension: '.ts',
+        folder: '__generated__',
+        filePerOperation: true,
+        inGeneratesOnly: true
+      },
+      plugins: ['typescript-operations'],
+      config: {
+        namingConvention: 'keep',
+        extractAllFieldsToTypesCompact: true,
+        printFieldsOnNewLines: true,
+        enumType: 'native',
+        nonOptionalTypename: true,
+        skipTypeNameForRoot: true,
+        omitOperationSuffix: true,
+        fragmentSuffix: '',
+        generatesOperationTypes: true,
+        defaultScalarType: 'any'
+      }
+    }
+  }
 }
 
 export default config
@@ -147,7 +160,11 @@ const config: CodegenConfig = {
 export default config
 ```
 
-With this configuration, `src/Component.ts` → `src/__generated__/Component.ts`, matching Apollo Tooling's output structure exactly.
+With this configuration, `src/Component.ts` → `src/__generated__/GetUser.ts`, matching Apollo Tooling's output structure exactly.
+
+If you need to generate files per-component (default to GraphQL Codegen), remove the following
+config option: `filePerOperation: true` (or set it to `false`). Then, the output will be:
+`src/Component.ts` → `src/__generated__/Component.ts`
 
 ## Type naming conventions
 
@@ -218,6 +235,7 @@ const config: CodegenConfig = {
       plugins: ['typescript-operations'],
       config: {
         extractAllFieldsToTypesCompact: true,
+        namingConvention: 'keep',
         enumType: 'native'
       }
     }
@@ -275,7 +293,10 @@ const config: CodegenConfig = {
         // Don't add 'Query'/'Mutation'/'Subscription' suffixes to operation result types
         omitOperationSuffix: true,
         // Don't add 'Fragment' suffix to fragment result types
-        fragmentSuffix: ''
+        fragmentSuffix: '',
+        generatesOperationTypes: true,
+        // Default is 'unknown'; to match Apollo tooling we need to put 'any'
+        defaultScalarType: 'any'
       }
     }
   }
@@ -288,13 +309,50 @@ 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. In very rare cases, the names generated by GraphQL Codegen don’t match Apollo Tooling’s. Update these cases manually.
+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.
+
+2. Enum file location.
 
-2. Enum file location. Occasionally, GraphQL Codegen places enums in a different file. If an enum is missing, check nearby generated files and adjust your imports accordingly.
+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. Occasional mismatch between `Type | null` and `Type | null | undefined`.
+3. `is possibly null` and `has any type` typecheck bugs.
+
+These bugs has to be fixed.
+
+For `is possibly null` bug, asserting for not null or adding `!` will fix most cases:
+
+```
+  getUser.name -> getUser!.name
+```
 
-4. Occasional `is possibly null` and `has any type` typecheck bugs.
+For `has any type` bug - a proper type needs to be determined.
+
+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).
+```
+
+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.
+```
 
 ## Further reading