Docs update for apollo-tooling migration: package versions updated + minor improvements (#10857)

* docs update for apollo-tooling migration

* prettier

---------

Co-authored-by: Igor Kusakov <igor@kusakov.com>

Author: ikusakov2

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

@@ -1,14 +1,14 @@
 ---
 description:
-  Migrating from Apollo Tooling (apollo client:codegen) to GraphQL Code Generator. What has changed?
-  How to migrate? What configuration options replace Apollo Tooling's behaviour?
+  Migrating from Apollo-tooling (apollo client:codegen) to GraphQL Code Generator. What has changed?
+  How to migrate? What configuration options replace apollo-tooling's behaviour?
 ---
 
 import { Callout, Tabs } from '@theguild/components'
 
-# Migrating from Apollo Tooling to GraphQL Code Generator
+# Migrating from Apollo-tooling to GraphQL Code Generator
 
-[Apollo Tooling](https://github.com/apollographql/apollo-tooling) (the `apollo` CLI, specifically
+[Apollo-tooling](https://github.com/apollographql/apollo-tooling) (the `apollo` CLI, specifically
 `apollo client:codegen`) is a code generation tool that generates TypeScript types from GraphQL
 operations for use with Apollo Client.
 
@@ -22,7 +22,7 @@ of GraphQL Codegen.
 
 ## Installation
 
-Remove Apollo Tooling and install GraphQL Code Generator:
+Remove apollo-tooling and install GraphQL Code Generator:
 
 <Tabs items={['Before', 'After']}>
 <Tabs.Tab>
@@ -50,19 +50,19 @@ npm i -D @graphql-codegen/cli @graphql-codegen/typescript-operations @graphql-co
 {
   "devDependencies": {
     ...
-    "@graphql-codegen/cli": "7.0.1",
-    "@graphql-codegen/near-operation-file-preset": "5.2.0",
-    "@graphql-codegen/typescript-operations": "6.0.0",
+    "@graphql-codegen/cli": "^7.0.0",
+    "@graphql-codegen/near-operation-file-preset": "^5.2.0",
+    "@graphql-codegen/typescript-operations": "^6.0.0",
     ...
   }
 }
 ```
 
 ## Configuration
 
-Apollo Tooling is configured via `apollo.config.js` (or `apollo.config.ts`) and invoked with
+Apollo-tooling is configured via `apollo.config.js` (or `apollo.config.ts`) and invoked with
 `apollo client:codegen`. GraphQL Code Generator uses a `codegen.ts` file and is invoked with
-`graphql-codegen`.
+`graphql-codegen` cli command or programmatically.
 
 <Tabs items={['Before', 'After']}>
 <Tabs.Tab>
@@ -118,9 +118,9 @@ export default config
 
 ## Per-operation file generation with `near-operation-file`
 
-Apollo Tooling's default behaviour is to generate one TypeScript file per graphql operation, placed
+Apollo-tooling's default behaviour is to generate one TypeScript file per graphql operation, placed
 in a `__generated__` folder next to the source. For example, given `src/Component.ts` containing a
-query `GetUser`, Apollo Tooling produces `src/__generated__/GetUser.ts`.
+query `GetUser`, apollo-tooling produces `src/__generated__/GetUser.ts`.
 
 GraphQL Code Generator replicates this with the `filePerOperation: true` parameter of the
 [`near-operation-file` preset](https://the-guild.dev/graphql/codegen/plugins/presets/near-operation-file-preset).
@@ -136,7 +136,7 @@ const config: CodegenConfig = {
       presetConfig: {
         extension: '.ts',
         folder: '__generated__',
-        filePerOperation: true // Generate type files per-operation (not per-component)
+        filePerOperation: true // Generate type files per-operation (not per-source file)
       },
       ...
     }
@@ -150,23 +150,33 @@ export default config
 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
+If you need to generate files per-source file (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
+## Nested field types naming conventions
 
-Apollo Tooling generates type names using **only field names**, omitting the GraphQL object type
-name:
+Nested fields are the fields inside operation result object.
+
+Apollo-tooling generates nested field type names using **only field names**, omitting the GraphQL
+object type name:
 
 ```ts
-// Apollo Tooling output
+// Apollo-tooling output
 export type GetUserQuery_user = { ... };
 export type GetUserQuery_user_address = { ... };
 ```
 
-To achieve similar naming with GraphQL Codegen use the `extractAllFieldsToTypesCompact: true`
-configuration option:
+By default GraphQL Codegen always adds field types:
+
+```ts
+// GraphQL Codegen output
+export type GetUserQuery_user_User = { ... };
+export type GetUserQuery_user_User_address_Address = { ... };
+```
+
+To achieve naming similar to apollo-tooling with GraphQL Codegen use the
+`extractAllFieldsToTypesCompact: true` configuration option:
 
 ```ts filename="codegen.ts"
 const config: CodegenConfig = {
@@ -183,11 +193,11 @@ const config: CodegenConfig = {
 
 ## Enum types
 
-Apollo Tooling generates enums as native TypeScript `enum` declarations and references them directly
+Apollo-tooling generates enums as native TypeScript `enum` declarations and references them directly
 by name (without any namespace prefix):
 
 ```ts
-// Apollo Tooling output
+// Apollo-tooling output
 export enum UserManagerRoleType {
   ROLE_TYPE_1 = 'ROLE_TYPE_1',
   ROLE_TYPE_2 = 'ROLE_TYPE_2',
@@ -200,7 +210,7 @@ export type GetUserQuery_user_manager = {
 ```
 
 GraphQL Code Generator generates string literal union types by default. To produce native `enum`
-declarations matching Apollo Tooling's output, set `enumType: 'native'`:
+declarations matching apollo-tooling's output, set `enumType: 'native'`:
 
 ```ts filename="codegen.ts"
 const config: CodegenConfig = {
@@ -233,7 +243,7 @@ for all available enum type options.
 
 ## Recommended configuration
 
-Below is a configuration that produces output closely matching Apollo Tooling's behaviour, including
+Below is a configuration that produces output closely matching apollo-tooling's behaviour, including
 per-file generation, enum output, and type naming:
 
 ```ts filename="codegen.ts"
@@ -243,7 +253,7 @@ const config: CodegenConfig = {
   // since codegen 6.0, we can also pass pre-parsed GraphQLSchema here (for caching - when running codegen in a loop on a monorepo with many packages)
   schema: './schema.graphql',
   documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
-  // `externalDocuments` are read-only documents that are loaded but do not generate output.
+  // `externalDocuments` are read-only documents that are loaded but no output is generated for them.
   // They are used to include fragments from another package in a monorepo without generating unnecessary files.
   externalDocuments: [
     '../other-package/src/**/*.{ts,tsx}',
@@ -262,13 +272,13 @@ const config: CodegenConfig = {
     }
   },
   config: {
-    // Extract nested field types to named types (matches Apollo Tooling naming)
+    // Extract nested field types to named types (matches apollo-tooling naming)
     extractAllFieldsToTypesCompact: true,
     // Keep original naming as-is (no camelCase conversion)
     namingConvention: 'keep',
     // Print each field on its own line for readability
     printFieldsOnNewLines: true,
-    // Use native TypeScript enums (matches Apollo Tooling enum output)
+    // Use native TypeScript enums (matches apollo-tooling enum output)
     enumType: 'native',
     // Always include __typename in result types
     nonOptionalTypename: true,
@@ -278,7 +288,7 @@ const config: CodegenConfig = {
     omitOperationSuffix: true,
     // Don't add 'Fragment' suffix to fragment result types
     fragmentSuffix: '',
-    // Default is 'unknown'; to match Apollo tooling we need to put 'any'
+    // Default is 'unknown'; to match apollo-tooling we need to put 'any'
     defaultScalarType: 'any'
   }
 }
@@ -288,17 +298,17 @@ export default config
 
 ## Manual changes
 
-The setup above closely mimics Apollo Tooling but isn’t an exact match. The following items may
-require manual fixes:
+The setup above closely mimics apollo-tooling (99.98% similarity in our tests) but isn’t an exact
+match. The following items may require manual fixes:
 
 #### 1. Nested field types naming.
 
-In very rare cases, the field names generated by GraphQL Codegen don’t match Apollo Tooling’s.
+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.
 
-Occasionally, GraphQL Codegen places enums in a different file then Apollo Tooling. If an enum is
+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.