Codegen
PluginsTypeScripttypescript
💡

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.
For building a GraphQL server schema we recommend using the server-preset.

TypeScript

Package nameWeekly DownloadsVersionLicenseUpdated
@graphql-codegen/typescriptDownloadsVersionLicenseNov 22nd, 2024

Installation

npm i -D @graphql-codegen/typescript

This plugin generates the base TypeScript types, based on your GraphQL schema.

The types generated by this plugin are simple, and refers to the exact structure of your schema, and it’s used as the base types for other plugins (such as typescript-operations / typescript-resolvers)

Config API Reference

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

constEnums

type: boolean default: false

Will prefix every generated enum with const, you can read more about const enums here: https://www.typescriptlang.org/docs/handbook/enums.html.

Usage Examples

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

enumsAsTypes

type: boolean default: false

Generates enum as TypeScript string union type instead of an enum. Useful if you wish to generate .d.ts declaration file instead of .ts, or if you want to avoid using TypeScript enums due to bundle size concerns

Usage Examples

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

numericEnums

type: boolean default: false

Controls whether to preserve typescript enum values as numbers

Usage Examples

codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  generates: {
    'path/to/file.ts': {
      plugins: ['typescript'],
      config: {
        numericEnums: 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'],
      config: {
        enumsAsTypes: true,
        futureProofEnums: true
      }
    }
  }
}
export default config

futureProofUnions

type: boolean default: false

This option controls whether or not a catch-all entry is added to union 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'],
      config: {
        futureProofUnions: true
      }
    }
  }
}
export default config

enumsAsConst

type: boolean default: false

Generates enum as TypeScript const assertions instead of enum. This can even be used to enable enum-like patterns in plain JavaScript code if you choose not to use TypeScript’s enum construct.

Usage Examples

codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  generates: {
    'path/to/file.ts': {
      plugins: ['typescript'],
      config: {
        enumsAsConst: 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

codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  generates: {
    'path/to/file.ts': {
      plugins: ['typescript'],
      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). Interacts well with preResolveTypes: true

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: {
        onlyOperationTypes: 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

maybeValue

type: string default: T | null

Allow to override the type value of Maybe.

Usage Examples

Allow undefined
codegen.ts
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:
codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  generates: {
    'path/to/file.ts': {
      plugins: ['typescript', 'typescript-resolvers'],
      config: {
        maybeValue: 'T extends PromiseLike<infer U> ? Promise<U | null> : T | null'
      }
    }
  }
}
export default config

inputMaybeValue

type: string default: Maybe<T>

Allow to override the type value of Maybe for input types and arguments. This is useful in case you want to differentiate between the wrapper of input and output types. By default, this type just refers to Maybe type, but you can override its definition.

Usage Examples

Allow undefined
codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  generates: {
    'path/to/file.ts': {
      plugins: ['typescript'],
      config: {
        inputMaybeValue: 'T | null | undefined'
      }
    }
  }
}
export default config
Allow null in resolvers:
codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  generates: {
    'path/to/file.ts': {
      plugins: ['typescript'],
      config: {
        inputMaybeValue: 'T extends PromiseLike<infer U> ? Promise<U | null> : T | null'
      }
    }
  }
}
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

Disable all export from a file
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

disableDescriptions

type: boolean default: false

Set the value to true in order to disable all description generation.

Usage Examples

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

useImplementingTypes

type: boolean default: false

When a GraphQL interface is used for a field, this flag will use the implementing types, instead of the interface itself.

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: {
        useImplementingTypes: true
      }
    }
  }
}
export default config

wrapEntireFieldDefinitions

type: boolean default: false

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.

allowEnumStringTypes

type: boolean

Allow using enum string values directly.

Usage Examples

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

addUnderscoreToArgsType

type: boolean

Adds _ to generated Args types in order to avoid duplicate identifiers.

Usage Examples

With Custom Values
codegen.ts
 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
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;

declarationKind

type: DeclarationKindConfig | string (values: abstract class, class, interface, type)

Overrides the default output for various GraphQL elements.

Usage Examples

Override all declarations
codegen.ts
 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
codegen.ts
 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
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;

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
codegen.ts
 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
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         wrapFieldDefinitions: 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
codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         ignoreEnumValuesFromSchema: true,
       },
     },
   },
 };
 export default config;

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\
codegen.ts
 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

codegen.ts
 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

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: any

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: '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

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;

skipTypename

type: boolean default: false

Does not add __typename to the generated types, unless it was specified in the selection set.

Usage Examples

codegen.ts
 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

codegen.ts
 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

codegen.ts
 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). “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.

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.

typed-document-nodeapollo-angular