Codegen
DocumentationMigration GuidesApollo Tooling -> GraphQL Code Generator

Migrating from Apollo Tooling to GraphQL Code Generator

Apollo Tooling (the apollo CLI, specifically apollo client:codegen) is a code generation tool that generates TypeScript types from GraphQL operations for use with Apollo Client.

This guide explains how to replace it with GraphQL Code Generator, which is actively maintained, more flexible, and supports a broader range of use cases.

💡

This setup is available in the next major version of graphql-code-generator and graphql-code-generator-community.

Installation

Remove Apollo Tooling and install GraphQL Code Generator:

npm uninstall apollo

Required packages

PackageDescription
@graphql-codegen/cliCore CLI that runs the code generator
@graphql-codegen/typescript-operationsPlugin that generates TypeScript types for GraphQL operations
@graphql-codegen/near-operation-file-presetPreset that places generated files next to their source operations
package.json
{
  "devDependencies": {
    ...
    "@graphql-codegen/cli": "...",
    "@graphql-codegen/typescript-operations": "...",
    "@graphql-codegen/near-operation-file-preset": "..."
    ...
  }
}

Configuration

Apollo Tooling is configured via apollo.config.js (or apollo.config.ts) and invoked with apollo client:codegen. GraphQL Code Generator uses a codegen.ts file and is invoked with graphql-codegen.

apollo.config.js
module.exports = {
  client: {
    service: {
      name: 'my-service',
      localSchemaFile: './schema.graphql',
    },
    includes: ['./src/**/*.tsx', './src/**/*.ts'],
  },
}
apollo client:codegen --target=typescript --outputFlat src/__generated__/types.ts

Add a script to your package.json to run the code generator:

package.json
{
  "scripts": {
    "codegen": "graphql-codegen"
  }
}

Per-file generation with near-operation-file

Apollo Tooling’s default behaviour is to generate one TypeScript file per graphql operation, placed in a __generated__ folder next to the source. For example, given src/Component.ts containing a query GetUser, Apollo Tooling produces src/__generated__/GetUser.ts.

GraphQL Code Generator replicates this with the near-operation-file preset.

codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: './schema.graphql',
  documents: ['./src/**/*.{ts,tsx}', '!./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`)
      },
      plugins: ['typescript-operations']
    }
  }
}
 
export default config

With this configuration, src/Component.ts → src/__generated__/GetUser.ts, matching Apollo Tooling’s output structure exactly.

If you need to generate files per-component (default to GraphQL Codegen), remove the following config option: filePerOperation: true (or set it to false). Then, the output will be: src/Component.ts → src/__generated__/Component.ts

Type naming conventions

Apollo Tooling generates type names using only field names, omitting the GraphQL object type name:

// Apollo Tooling output
export type GetUserQuery_user = { ... };
export type GetUserQuery_user_address = { ... };

To achieve similar naming with GraphQL Codegen use the extractAllFieldsToTypesCompact: true configuration option:

codegen.ts
const config: CodegenConfig = {
  schema: './schema.graphql',
  documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
  generates: {
    './src/': {
      preset: 'near-operation-file',
      presetConfig: {
        extension: '.ts',
        folder: '__generated__',
        filePerOperation: true,
        inGeneratesOnly: true
      },
      plugins: ['typescript-operations'],
      config: {
        extractAllFieldsToTypesCompact: true
      }
    }
  }
}

Enum types

Apollo Tooling generates enums as native TypeScript enum declarations and references them directly by name (without any namespace prefix):

// Apollo Tooling output
export enum UserManagerRoleType {
  ROLE_TYPE_1 = 'ROLE_TYPE_1',
  ROLE_TYPE_2 = 'ROLE_TYPE_2',
  ROLE_TYPE_3 = 'ROLE_TYPE_3'
}
 
export type GetUserQuery_user_manager = {
  roleType: UserManagerRoleType
}

GraphQL Code Generator generates string literal union types by default. To produce native enum declarations matching Apollo Tooling’s output, set enumType: 'native':

codegen.ts
const config: CodegenConfig = {
  schema: './schema.graphql',
  documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
  generates: {
    './src/': {
      preset: 'near-operation-file',
      presetConfig: {
        extension: '.ts',
        folder: '__generated__',
        filePerOperation: true,
        inGeneratesOnly: true
      },
      plugins: ['typescript-operations'],
      config: {
        extractAllFieldsToTypesCompact: true,
        namingConvention: 'keep',
        enumType: 'native'
      }
    }
  }
}
⚠️

Native TypeScript enum declarations incur a runtime cost (they compile to JavaScript objects). If you only need type-level checking, consider using the default string-literal enum type instead:

type UserManagerRoleType = 'ROLE_TYPE_1' | 'ROLE_TYPE_2' | 'ROLE_TYPE_3'

See the typescript-operations configuration reference for all available enum type options.

Recommended configuration

Below is a configuration that produces output closely matching Apollo Tooling’s behaviour, including per-file generation, enum output, and type naming:

codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: './schema.graphql',
  documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
  generates: {
    './src/': {
      preset: 'near-operation-file',
      presetConfig: {
        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
      },
      plugins: ['typescript-operations'],
      config: {
        // Keep original naming as-is (no camelCase conversion)
        namingConvention: 'keep',
        // Extract nested field types to named types (matches Apollo Tooling naming)
        extractAllFieldsToTypesCompact: true,
        // Print each field on its own line for readability
        printFieldsOnNewLines: true,
        // Use native TypeScript enums (matches Apollo Tooling enum output)
        enumType: 'native',
        // Always include __typename in result types
        nonOptionalTypename: true,
        // Don't add __typename to root query/mutation/subscription types
        skipTypeNameForRoot: true,
        // Don't add 'Query'/'Mutation'/'Subscription' suffixes to operation result types
        omitOperationSuffix: true,
        // Don't add 'Fragment' suffix to fragment result types
        fragmentSuffix: '',
        generatesOperationTypes: true,
        // Default is 'unknown'; to match Apollo tooling we need to put 'any'
        defaultScalarType: 'any'
      }
    }
  }
}
 
export default config

Manual changes

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.

In very rare cases, the names generated by GraphQL Codegen don’t match Apollo Tooling’s. Update these cases manually.

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

  1. is possibly null and has any type typecheck bugs.

These bugs has to be fixed.

For is possibly null bug, asserting for not null or adding ! will fix most cases:

  getUser.name -> getUser!.name

For has any type bug - a proper type needs to be determined.

  1. 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<T>', set to 'T | null | undefined' if necessary
  avoidOptionals: Replaces ? optional modifier with explicit Maybe<T>. 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).
  1. 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.

Further reading

typescript-operations and client-preset v5.0 -> v6.0