From 1ef5824eec73c3cdb92ae8365687a7691b45a1cf Mon Sep 17 00:00:00 2001 From: Igor Kusakov Date: Tue, 14 Apr 2026 15:49:19 -0400 Subject: [PATCH 1/4] updated apollo migration docs --- .../pages/docs/migration/apollo-tooling.mdx | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/website/src/pages/docs/migration/apollo-tooling.mdx b/website/src/pages/docs/migration/apollo-tooling.mdx index 727539c8159..2a88e987359 100644 --- a/website/src/pages/docs/migration/apollo-tooling.mdx +++ b/website/src/pages/docs/migration/apollo-tooling.mdx @@ -93,14 +93,14 @@ 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 +154,14 @@ 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 +196,14 @@ 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 +239,14 @@ 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,6 +284,9 @@ 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 any output. + // They are used to include fragments from another package within a monorepo. + externalDocuments: ['../other-package/src/**/*.{ts,tsx}', '!../other-package/src/**/__generated__/**'], generates: { './src/': { preset: 'near-operation-file', @@ -291,9 +294,7 @@ const config: CodegenConfig = { 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: { @@ -331,7 +332,7 @@ 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 +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. From cbdebe8a1b0b6bcbba201f98b64addb6d9942b0d Mon Sep 17 00:00:00 2001 From: Igor Kusakov Date: Wed, 15 Apr 2026 15:37:36 -0400 Subject: [PATCH 2/4] better comments --- .../pages/docs/migration/apollo-tooling.mdx | 38 +++++++++---------- 1 file changed, 17 insertions(+), 21 deletions(-) diff --git a/website/src/pages/docs/migration/apollo-tooling.mdx b/website/src/pages/docs/migration/apollo-tooling.mdx index 2a88e987359..d363dbfc4c0 100644 --- a/website/src/pages/docs/migration/apollo-tooling.mdx +++ b/website/src/pages/docs/migration/apollo-tooling.mdx @@ -284,7 +284,7 @@ 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 any output. + // `externalDocuments` are read-only documents that are loaded but do not generate output. // They are used to include fragments from another package within a monorepo. externalDocuments: ['../other-package/src/**/*.{ts,tsx}', '!../other-package/src/**/__generated__/**'], generates: { @@ -330,17 +330,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 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. @@ -352,30 +352,26 @@ 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', set to 'T | null | undefined' if necessary - avoidOptionals: Replaces ? optional modifier with explicit Maybe. 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`, set to `T | null | undefined` if necessary +* **avoidOptionals**: Replaces ? optional modifier with explicit `Maybe`. 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 From 205f8ddded5fbb7706009e376fff622b925a7f12 Mon Sep 17 00:00:00 2001 From: Igor Kusakov Date: Wed, 15 Apr 2026 15:46:34 -0400 Subject: [PATCH 3/4] better comments --- website/src/pages/docs/migration/apollo-tooling.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/pages/docs/migration/apollo-tooling.mdx b/website/src/pages/docs/migration/apollo-tooling.mdx index d363dbfc4c0..68ccb9fcf57 100644 --- a/website/src/pages/docs/migration/apollo-tooling.mdx +++ b/website/src/pages/docs/migration/apollo-tooling.mdx @@ -285,7 +285,7 @@ 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 within a monorepo. + // 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/': { From ca9984f7a654c221ae51d7c3fd0443c479af6e31 Mon Sep 17 00:00:00 2001 From: Eddy Nguyen Date: Sat, 18 Apr 2026 21:01:40 +1000 Subject: [PATCH 4/4] Format --- .../pages/docs/migration/apollo-tooling.mdx | 58 +++++++++++++------ 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/website/src/pages/docs/migration/apollo-tooling.mdx b/website/src/pages/docs/migration/apollo-tooling.mdx index 68ccb9fcf57..8bf23cd91cf 100644 --- a/website/src/pages/docs/migration/apollo-tooling.mdx +++ b/website/src/pages/docs/migration/apollo-tooling.mdx @@ -93,7 +93,10 @@ 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__/**'], + externalDocuments: [ + '../other-package/src/**/*.{ts,tsx}', + '!../other-package/src/**/__generated__/**' + ], generates: { './src/': { preset: 'near-operation-file', @@ -154,7 +157,10 @@ 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__/**'], + externalDocuments: [ + '../other-package/src/**/*.{ts,tsx}', + '!../other-package/src/**/__generated__/**' + ], generates: { './src/': { preset: 'near-operation-file', @@ -196,7 +202,10 @@ configuration option: const config: CodegenConfig = { schema: './schema.graphql', documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'], - externalDocuments: ['../other-package/src/**/*.{ts,tsx}', '!../other-package/src/**/__generated__/**'], + externalDocuments: [ + '../other-package/src/**/*.{ts,tsx}', + '!../other-package/src/**/__generated__/**' + ], generates: { './src/': { preset: 'near-operation-file', @@ -239,7 +248,10 @@ 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__/**'], + externalDocuments: [ + '../other-package/src/**/*.{ts,tsx}', + '!../other-package/src/**/__generated__/**' + ], generates: { './src/': { preset: 'near-operation-file', @@ -286,7 +298,10 @@ const config: CodegenConfig = { 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__/**'], + externalDocuments: [ + '../other-package/src/**/*.{ts,tsx}', + '!../other-package/src/**/__generated__/**' + ], generates: { './src/': { preset: 'near-operation-file', @@ -332,8 +347,8 @@ 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. 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. @@ -356,22 +371,29 @@ For `has any type` bug - a proper type needs to be determined. 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`, set to `T | null | undefined` if necessary -* **avoidOptionals**: Replaces ? optional modifier with explicit `Maybe`. 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`, set to `T | null | undefined` if necessary +- **avoidOptionals**: Replaces ? optional modifier with explicit `Maybe`. 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. +- **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