Codegen
PluginsTypeScriptoperations
💡

This plugin is meant to be used for low-level use cases or as building block for presets.
For building a GraphQL client application we recommend using the client-preset.

TypeScript Operations

Package nameWeekly DownloadsVersionLicenseUpdated
@graphql-codegen/typescript-operationsDownloadsVersionLicenseJan 15th, 2026

Installation

npm i -D @graphql-codegen/typescript-operations
⚠️

Usage Requirements In order to use this GraphQL Codegen plugin, please make sure that you have GraphQL operations (query / mutation / subscription and fragment) set as documents: … in your codegen.yml.

Without loading your GraphQL operations (query, mutation, subscription and fragment), you won’t see any change in the generated output.

This plugin generates TypeScript types based on your GraphQLSchema and your GraphQL operations and fragments. It generates types for your GraphQL documents: Query, Mutation, Subscription and Fragment.

Note: In most configurations, this plugin requires you to use `typescript as well, because it depends on its base types.

Config API Reference

arrayInputCoercion

type: boolean default: true

The GraphQL spec allows arrays and a single primitive value for list input. This allows to deactivate that behavior to only accept arrays instead of single values. If set to false, the definition: query foo(bar: [Int!]!): Foo will output bar: Array<Int> instead of bar: Array<Int> | Int for the variable part.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript'],
       config: {
         arrayInputCoercion: false
       },
     },
   },
 };
 export default config;

avoidOptionals

type: AvoidOptionalsConfig | boolean default: false

This will cause the generator to avoid using TypeScript optionals (?) on types, so the following definition: type A { myField: String } will output myField: Maybe<string> instead of myField?: Maybe<string>.

Usage Examples

Override all definition types
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript'],
       config: {
         avoidOptionals: true
       },
     },
   },
 };
 export default config;
Override only specific definition types
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript'],
       config: {
         avoidOptionals: {
           field: true
           inputValue: true
           object: true
           defaultValue: true
         }
       },
     },
   },
 };
 export default config;

immutableTypes

type: boolean default: false

Generates immutable types by adding readonly to properties and uses ReadonlyArray.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript'],
       config: {
         immutableTypes: true
       },
     },
   },
 };
 export default config;

flattenGeneratedTypes

type: boolean default: false

Flatten fragment spread and inline fragments into a simple selection set before generating.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript', 'typescript-operations'],
       config: {
         flattenGeneratedTypes: true
       },
     },
   },
 };
 export default config;

flattenGeneratedTypesIncludeFragments

type: boolean default: false

Include all fragments types when flattenGeneratedTypes is enabled.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript', 'typescript-operations'],
       config: {
         flattenGeneratedTypes: true,
         flattenGeneratedTypesIncludeFragments: true
       },
     },
   },
 };
 export default config;

noExport

type: boolean default: false

Set to true in order to generate output without export modifier. This is useful if you are generating .d.ts file and want it to be globally available.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript'],
       config: {
         noExport: true
       },
     },
   },
 };
 export default config;

addOperationExport

type: boolean default: false

Add const export of the operation name to output file. Pay attention that the file should be d.ts. You can combine it with near-operation-file preset and therefore the types will be generated along with graphql file. Then you need to set extension in presetConfig to be .gql.d.ts and by that you can import gql file in ts files. It will allow you to get everything with one import:

import { GetClient, GetClientQuery, GetClientQueryVariables } from './GetClient.gql.js'

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     "./typings/api.ts": {
       "plugins": [
           "typescript"
       ]
   },
   "./": {
       "preset": "near-operation-file",
       "presetConfig": {
           "baseTypesPath": "./typings/api.ts",
           "extension": ".gql.d.ts"
       },
       "plugins": [
           "@graphql-codegen/typescript-operations"
       ],
       "config": {
           "addOperationExport": true
       }
   }
 };
 export default config;

maybeValue

type: string default: T | null

Allows overriding the type value of nullable fields to match GraphQL client’s runtime behaviour.

Usage Examples

Allow undefined

By default, a GraphQL server will return either the expected type or null for a nullable field. maybeValue option could be used to change this behaviour if your GraphQL client does something different such as returning undefined.

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript-operations'],
       config: {
         maybeValue: 'T | null | undefined'
       },
     },
   },
 };
 export default config;

inputMaybeValue

type: string default: T | null | undefined

Allows overriding the type of Input and Variables nullable types.

Usage Examples

Disallow undefined

Disallowing undefined is useful if you want to force explicit null to be passed in as Variables to the server. Use inputMaybeValue: 'T | null' with avoidOptionals.inputValue: true to achieve this.

codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  generates: {
    'path/to/file.ts': {
      plugins: ['typescript-operations'],
      config: {
        avoidOptionals: {
          inputValue: true,
        },
        inputMaybeValue: 'T | null'
      }
    }
  }
}
export default config

allowUndefinedQueryVariables

type: boolean default: false

Adds undefined as a possible type for query variables

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript'],
       config: {
         allowUndefinedQueryVariables: true
       },
     },
   },
 };
 export default config;

nullability

type: object

Options related to handling nullability

Usage Examples

errorHandlingClient

An error handling client is a client which prevents the user from reading a null used as a placeholder for an error in a GraphQL response. The client may do so by throwing when an errored field is accessed (as is the case for graphql-toe), or when a fragment containing an error is read (as is the case for Relay’s @throwOnFieldError directive), or by preventing any data from being read if an error occurred (as with Apollo Client’s errorPolicy: "none").

When using error handling clients, a semantic non-nullable field can never be null. If a semantic non-nullable field’s value in the response is null, there must be a respective error. The error handling client will throw in this case, so the null value is never read.

To enable this option, install graphql-sock peer dependency:

npm install -D graphql-sock

Now, you can enable support for error handling clients:

codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  // ...
  generates: {
    'path/to/file.ts': {
      plugins: ['typescript', 'typescript-operations'],
      config: {
        nullability: {
          errorHandlingClient: true
        }
      },
    },
  },
};
export default config;

enumType

type: string (values: const, native, native-const, native-numeric, string-literal) default: string-literal

Controls the enum output type. Options: string-literal | native-numeric | const | native-const | native;

Usage Examples

codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  generates: {
    'path/to/file.ts': {
      plugins: ['typescript-operations'],
      config: {
        enumType: 'string-literal',
      }
    }
  }
}
export default config
 
### `enumValues`
 
  type: `EnumValuesMap`
  
  Overrides the default value of enum values declared in your GraphQL schema.
You can also map the entire enum to an external type by providing a string that of `module#type`.
 
   
#### Usage Examples
 
##### With Custom Values
```ts filename="codegen.ts"
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         enumValues: {
           MyEnum: {
             A: 'foo'
           }
         }
       },
     },
   },
 };
 export default config;
With External Enum
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         enumValues: {
           MyEnum: './my-file#MyCustomEnum',
         }
       },
     },
   },
 };
 export default config;
Import All Enums from a file
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         enumValues: {
           MyEnum: './my-file',
         }
       },
     },
   },
 };
 export default config;

ignoreEnumValuesFromSchema

type: boolean default: false

This will cause the generator to ignore enum values defined in GraphQLSchema

Usage Examples

Ignore enum values from schema
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         ignoreEnumValuesFromSchema: true,
       },
     },
   },
 };
 export default config;

futureProofEnums

type: boolean default: false

This option controls whether or not a catch-all entry is added to enum type definitions for values that may be added in the future. This is useful if you are using relay.

Usage Examples

codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  generates: {
    'path/to/file.ts': {
      plugins: ['typescript-operations'],
      config: {
        futureProofEnums: true
      }
    }
  }
}
export default config

skipTypeNameForRoot

type: boolean default: false

Avoid adding __typename for root types. This is ignored when a selection explicitly specifies __typename.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         skipTypeNameForRoot: true
       },
     },
   },
 };
 export default config;

nonOptionalTypename

type: boolean default: false

Automatically adds __typename field to the generated types, even when they are not specified in the selection set, and makes it non-optional

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         nonOptionalTypename: true
       },
     },
   },
 };
 export default config;

globalNamespace

type: boolean default: false

Puts all generated code under global namespace. Useful for Stencil integration.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         globalNamespace: true
       },
     },
   },
 };
 export default config;

operationResultSuffix

type: string default: (empty)

Adds a suffix to generated operation result type names

dedupeOperationSuffix

type: boolean default: false

Set this configuration to true if you wish to make sure to remove duplicate operation name suffix.

omitOperationSuffix

type: boolean default: false

Set this configuration to true if you wish to disable auto add suffix of operation name, like Query, Mutation, Subscription, Fragment.

exportFragmentSpreadSubTypes

type: boolean default: false

If set to true, it will export the sub-types created in order to make it easier to access fields declared under fragment spread.

experimentalFragmentVariables

type: boolean default: false

If set to true, it will enable support for parsing variables on fragments.

mergeFragmentTypes

type: boolean default: false

If set to true, merge equal fragment interfaces.

customDirectives

type: CustomDirectivesConfig

Configures behavior for use with custom directives from various GraphQL libraries.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript'],
       config: {
         customDirectives: {
           apolloUnmask: true
         }
       },
     },
   },
 };
 export default config;

generatesOperationTypes

type: boolean default: true

Whether to generate operation types such as Variables, Query/Mutation/Subscription selection set, and Fragment types This can be used with importSchemaTypesFrom to generate shared used Enums and Input.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript-operations'],
       config: {
         generatesOperationTypes: false,
       },
     },
   },
 };
 export default config;

importSchemaTypesFrom

type: string default: true

The absolute (prefixed with ~) or relative path from cwd to the shared used Enums and Input (See generatesOperationTypes).

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       plugins: ['typescript-operations'],
       config: {
         importSchemaTypesFrom: './path/to/shared-types.ts', // relative
         importSchemaTypesFrom: '~@my-org/package' // absolute
       },
     },
   },
 };
 export default config;

extractAllFieldsToTypes

type: boolean default: false

Extract all field types to their own types, instead of inlining them. This helps to reduce type duplication, and makes type errors more readable. It can also significantly reduce the size of the generated code, the generation time, and the typechecking time.

extractAllFieldsToTypesCompact

type: boolean default: false

Generates type names using only field names, omitting GraphQL type names. This matches the naming convention used by Apollo Tooling. For example, instead of Query_company_Company_office_Office_location_Location, it generates Query_company_office_location.

When this option is enabled, extractAllFieldsToTypes is automatically enabled as well.

strictScalars

type: boolean default: false

Makes scalars strict.

If scalars are found in the schema that are not defined in scalars an error will be thrown during codegen.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         strictScalars: true,
       },
     },
   },
 };
 export default config;

defaultScalarType

type: string default: unknown

Allows you to override the type that unknown scalars will have.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         defaultScalarType: 'any'
       },
     },
   },
 };
 export default config;

scalars

type: ScalarsMap_1

Extends or overrides the built-in scalars and custom GraphQL scalars to a custom type.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         scalars: {
           ID: {
             input: 'string',
             output: 'string | number'
           }
           DateTime: 'Date',
           JSON: '{ [key: string]: any }',
         }
       },
     },
   },
 };
 export default config;

namingConvention

type: NamingConvention_1 default: change-case-all#pascalCase

Allow you to override the naming convention of the output. You can either override all namings, or specify an object with specific custom naming convention per output. The format of the converter must be a valid module#method. Allowed values for specific output are: typeNames, enumValues. You can also use “keep” to keep all GraphQL names as-is. Additionally, you can set transformUnderscore to true if you want to override the default behavior, which is to preserve underscores.

Available case functions in change-case-all are camelCase, capitalCase, constantCase, dotCase, headerCase, noCase, paramCase, pascalCase, pathCase, sentenceCase, snakeCase, lowerCase, localeLowerCase, lowerCaseFirst, spongeCase, titleCase, upperCase, localeUpperCase and upperCaseFirst See more

Usage Examples

Override All Names
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         namingConvention: 'change-case-all#lowerCase',
       },
     },
   },
 };
 export default config;
Upper-case enum values
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         namingConvention: {
           typeNames: 'change-case-all#pascalCase',
           enumValues: 'change-case-all#upperCase',
         }
       },
     },
   },
 };
 export default config;
Keep names as is
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
        namingConvention: 'keep',
       },
     },
   },
 };
 export default config;
Remove Underscores
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         namingConvention: {
           typeNames: 'change-case-all#pascalCase',
           transformUnderscore: true
         }
       },
     },
   },
 };
 export default config;

typesPrefix

type: string default: (empty)

Prefixes all the generated types.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         typesPrefix: 'I',
       },
     },
   },
 };
 export default config;

typesSuffix

type: string default: (empty)

Suffixes all the generated types.

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         typesSuffix: 'I',
       },
     },
   },
 };
 export default config;

enumPrefix

type: boolean default: true

Allow you to disable prefixing for generated enums, works in combination with typesPrefix.

Usage Examples

Disable enum prefixes
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         typesPrefix: 'I',
         enumPrefix: false
       },
     },
   },
 };
 export default config;

enumSuffix

type: boolean default: true

Allow you to disable suffixing for generated enums, works in combination with typesSuffix.

Usage Examples

Disable enum suffixes
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         typesSuffix: 'I',
         enumSuffix: false
       },
     },
   },
 };
 export default config;

useTypeImports

type: boolean default: false

Will use import type {} rather than import {} when importing only types. This gives compatibility with TypeScript’s “importsNotUsedAsValues”: “error” option

Usage Examples

codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         useTypeImports: true
       },
     },
   },
 };
 export default config;

inlineFragmentTypes

type: string default: inline

Whether fragment types should be inlined into other operations. “inline” is the default behavior and will perform deep inlining fragment types within operation type definitions. “combine” is the previous behavior that uses fragment type references without inlining the types (and might cause issues with deeply nested fragment that uses list types). “mask” transforms the types for use with fragment masking. Useful when masked types are needed when not using the “client” preset e.g. such as combining it with Apollo Client’s data masking feature.

emitLegacyCommonJSImports

type: boolean default: true

Emit legacy common js imports. Default it will be true this way it ensure that generated code works with non-compliant bundlers.

importExtension

type: string[] | string (values: )

Append this extension to all imports. Useful for ESM environments that require file extensions in import statements.

printFieldsOnNewLines

type: boolean default: false

If you prefer to have each field in generated types printed on a new line, set this to true. This can be useful for improving readability of the resulting types, without resorting to running tools like Prettier on the output.

includeExternalFragments

type: boolean default: false

Whether to include external fragments in the generated code. External fragments are not defined in the same location as the operation definition.

nhostreact-apollo