diff --git a/website/src/pages/docs/migration/apollo-tooling.mdx b/website/src/pages/docs/migration/apollo-tooling.mdx index 727539c8159..8bf23cd91cf 100644 --- a/website/src/pages/docs/migration/apollo-tooling.mdx +++ b/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,6 +296,12 @@ 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', @@ -291,9 +309,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: { @@ -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', 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