TypeScript Document Nodes

Package name	Weekly Downloads	Version	License	Updated
`@graphql-codegen/typescript-document-nodes`				Nov 22nd, 2024

Installation

npm i -D @graphql-codegen/typescript-document-nodes

pnpm add -D @graphql-codegen/typescript-document-nodes

yarn add --dev @graphql-codegen/typescript-document-nodes

bun add --dev @graphql-codegen/typescript-document-nodes

This plugin generates TypeScript source .ts file from GraphQL files .graphql.

Config API Reference

`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;

`namePrefix`

type: string default: (empty)

Adds prefix to the name

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'src/api/user-service/queries.ts': {
       plugins: ['typescript-document-nodes'],
       config: {
         namePrefix: 'gql',
       },
     },
   },
 };
 export default config;

`nameSuffix`

type: string default: (empty)

Adds suffix to the name

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'src/api/user-service/queries.ts': {
       plugins: ['typescript-document-nodes'],
       config: {
         nameSuffix: 'Query'
       },
     },
   },
 };
 export default config;

`fragmentPrefix`

type: string default: (empty)

Adds prefix to the fragment variable

`fragmentSuffix`

type: string default: (empty)

Adds suffix to the fragment variable

`noGraphQLTag`

type: boolean default: false

Deprecated. Changes the documentMode to documentNode.

`gqlImport`

type: string default: graphql-tag#gql

Customize from which module will gql be imported from. This is useful if you want to use modules other than graphql-tag, e.g. graphql.macro.

Usage Examples

graphql.macro

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         gqlImport: 'graphql.macro#gql'
       },
     },
   },
 };
 export default config;

Gatsby

codegen.ts

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

`documentNodeImport`

type: string default: graphql#DocumentNode

Customize from which module will DocumentNode be imported from. This is useful if you want to use modules other than graphql, e.g. @graphql-typed-document-node.

`noExport`

type: boolean default: false

Set this configuration to true if you wish to tell codegen to generate code with no export identifier.

`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.

`operationResultSuffix`

type: string default: (empty)

Adds a suffix to generated operation result type names

`documentVariablePrefix`

type: string default: (empty)

Changes the GraphQL operations variables prefix.

`documentVariableSuffix`

type: string default: Document

Changes the GraphQL operations variables suffix.

`fragmentVariablePrefix`

type: string default: (empty)

Changes the GraphQL fragments variables prefix.

`fragmentVariableSuffix`

type: string default: FragmentDoc

Changes the GraphQL fragments variables suffix.

`documentMode`

type: DocumentMode_2 default: graphQLTag

Declares how DocumentNode are created:

graphQLTag: graphql-tag or other modules (check gqlImport) will be used to generate document nodes. If this is used, document nodes are generated on client side i.e. the module used to generate this will be shipped to the client
documentNode: document nodes will be generated as objects when we generate the templates.
documentNodeImportFragments: Similar to documentNode except it imports external fragments instead of embedding them.
external: document nodes are imported from an external file. To be used with importDocumentNodeExternallyFrom

Note that some plugins (like typescript-graphql-request) also supports string for this parameter.

`optimizeDocumentNode`

type: boolean default: true

If you are using documentMode: documentNode | documentNodeImportFragments, you can set this to true to apply document optimizations for your GraphQL document. This will remove all “loc” and “description” fields from the compiled document, and will remove all empty arrays (such as directives, arguments and variableDefinitions).

`importOperationTypesFrom`

type: string default: (empty)

This config is used internally by presets, but you can use it manually to tell codegen to prefix all base types that it’s using. This is useful if you wish to generate base types from typescript-operations plugin into a different file, and import it from there.

`importDocumentNodeExternallyFrom`

type: string default: (empty)

This config should be used if documentMode is external. This has 2 usage:

any string: This would be the path to import document nodes from. This can be used if we want to manually create the document nodes e.g. Use graphql-tag in a separate file and export the generated document
‘near-operation-file’: This is a special mode that is intended to be used with near-operation-file preset to import document nodes from those files. If these files are .graphql files, we make use of webpack loader.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         documentMode: 'external',
         importDocumentNodeExternallyFrom: 'path/to/document-node-file',
       },
     },
   },
 };
 export default config;

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         documentMode: 'external',
         importDocumentNodeExternallyFrom: 'near-operation-file',
       },
     },
   },
 };
 export default config;

`pureMagicComment`

type: boolean default: false

This config adds PURE magic comment to the static variables to enforce treeshaking for your bundler.

`experimentalFragmentVariables`

type: boolean default: false

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

`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;

`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.

Usage

With GitHub GraphQL API v4 schema and following GraphQL operation:

query Viewer {
  viewer {
    login
    name
  }
}

It will generate following TypeScript code:

import { DocumentNode } from 'graphql'
import gql from 'graphql-tag'
 
export const viewerQuery: DocumentNode = gql`
  query Viewer {
    viewer {
      login
      name
    }
  }
`

apollo-next fabbrica