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 name | Weekly Downloads | Version | License | Updated |
---|---|---|---|---|
@graphql-codegen/typescript-operations | Oct 14th, 2024 |
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
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
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
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
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
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
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
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file.ts': {
plugins: ['typescript'],
config: {
noExport: true
},
},
},
};
export default config;
globalNamespace
type: boolean
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
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
Allow to override the type value of Maybe
.
Usage Examples
Allow undefined
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file.ts': {
plugins: ['typescript'],
config: {
maybeValue: 'T | null | undefined'
},
},
},
};
export default config;
Allow null
in resolvers:
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file.ts': {
plugins: ['typescript'],
config: {
maybeValue: 'T extends PromiseLike<infer U> ? Promise<U | null> : T | null'
},
},
},
};
export default config;
allowUndefinedQueryVariables
type: boolean
default: false
Adds undefined as a possible type for query variables
Usage Examples
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file.ts': {
plugins: ['typescript'],
config: {
allowUndefinedQueryVariables: true
},
},
},
};
export default config;
preResolveTypes
type: boolean
default: true
Uses primitive types where possible.
Set to false
in order to use Pick
and take use the types generated by typescript
plugin.
Usage Examples
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
preResolveTypes: false
},
},
},
};
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
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
skipTypeNameForRoot: 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.
addUnderscoreToArgsType
type: boolean
Adds _
to generated Args
types in order to avoid duplicate identifiers.
Usage Examples
With Custom Values
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
addUnderscoreToArgsType: true
},
},
},
};
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
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
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
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
enumValues: {
MyEnum: './my-file',
}
},
},
},
};
export default config;
declarationKind
type: DeclarationKindConfig | string (values: abstract class, class, interface, type)
Overrides the default output for various GraphQL elements.
Usage Examples
Override all declarations
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
declarationKind: 'interface'
},
},
},
};
export default config;
Override only specific declarations
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
declarationKind: {
type: 'interface',
input: 'interface'
}
},
},
},
};
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
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
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
typesSuffix: 'I',
enumSuffix: false
},
},
},
};
export default config;
fieldWrapperValue
type: string
default: T
Allow you to add wrapper for field type, use T as the generic value. Make sure to set wrapFieldDefinitions
to true
in order to make this flag work.
Usage Examples
Allow Promise
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
wrapFieldDefinitions: true,
fieldWrapperValue: 'T | Promise<T>',
},
},
},
};
export default config;
wrapFieldDefinitions
type: boolean
default: false
Set to true
in order to wrap field definitions with FieldWrapper
.
This is useful to allow return types such as Promises and functions.
Usage Examples
Enable wrapping fields
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
wrapFieldDefinitions: true,
},
},
},
};
export default config;
onlyEnums
type: boolean
default: false
This will cause the generator to emit types for enums only
Usage Examples
Override all definition types
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
onlyEnums: true,
},
},
},
};
export default config;
onlyOperationTypes
type: boolean
default: false
This will cause the generator to emit types for operations only (basically only enums and scalars)
Usage Examples
Override all definition types
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
onlyOperationTypes: true,
},
},
},
};
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
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
ignoreEnumValuesFromSchema: true,
},
},
},
};
export default config;
wrapEntireFieldDefinitions
type: boolean
default: true
Set to true
in order to wrap field definitions with EntireFieldWrapper
.
This is useful to allow return types such as Promises and functions for fields.
Differs from wrapFieldDefinitions
in that this wraps the entire field definition if i.e. the field is an Array, while
wrapFieldDefinitions
will wrap every single value inside the array.
entireFieldWrapperValue
type: string
default: T | Promise<T> | (() => T | Promise<T>)
Allow to override the type value of EntireFieldWrapper
. This wrapper applies outside of Array and Maybe
unlike fieldWrapperValue
, that will wrap the inner type.
directiveArgumentAndInputFieldMappings
type: DirectiveArgumentAndInputFieldMappings
Replaces a GraphQL scalar with a custom type based on the applied directive on an argument or input field.
You can use both module#type
and module#namespace#type
syntax.
Will NOT work with introspected schemas since directives are not exported.
Only works with directives on ARGUMENT_DEFINITION or INPUT_FIELD_DEFINITION.
WARNING: Using this option does only change the type definitions.
For actually ensuring that a type is correct at runtime you will have to use schema transforms (e.g. with @graphql-tools/utils mapSchema) that apply those rules! Otherwise, you might end up with a runtime type mismatch which could cause unnoticed bugs or runtime errors.
Please use this configuration option with care!
Usage Examples
Custom Context Type\
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
directiveArgumentAndInputFieldMappings: {
AsNumber: 'number',
AsComplex: './my-models#Complex',
}
},
},
},
};
export default config;
directiveArgumentAndInputFieldMappingTypeSuffix
type: string
Adds a suffix to the imported names to prevent name clashes.
Usage Examples
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
directiveArgumentAndInputFieldMappings: 'Model'
},
},
},
};
export default config;
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
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: any
Allows you to override the type that unknown scalars will have.
Usage Examples
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
defaultScalarType: 'unknown'
},
},
},
};
export default config;
scalars
type: ScalarsMap_1
Extends or overrides the built-in scalars and custom GraphQL scalars to a custom type.
Usage Examples
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
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
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
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
namingConvention: 'keep',
},
},
},
};
export default config;
Remove Underscores
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
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
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
typesSuffix: 'I',
},
},
},
};
export default config;
skipTypename
type: boolean
default: false
Does not add __typename
to the generated types, unless it was specified in the selection set.
Usage Examples
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
skipTypename: 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
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
nonOptionalTypename: true
},
},
},
};
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
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
// ...
generates: {
'path/to/file': {
// plugins...
config: {
useTypeImports: true
},
},
},
};
export default config;
dedupeFragments
type: boolean
default: false
Removes fragment duplicates for reducing data transfer. It is done by removing sub-fragments imports from fragment definition Instead - all of them are imported to the Operation node.
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).
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.
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.
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.