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__/Component.ts, matching Apollo Tooling’s output structure exactly.

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,
        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: ''
      }
    }
  }
}
 
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.

  2. Enum file location. Occasionally, GraphQL Codegen places enums in a different file. If an enum is missing, check nearby generated files and adjust your imports accordingly.

  3. Occasional mismatch between Type | null and Type | null | undefined.

  4. Occasional is possibly null and has any type typecheck bugs.

Further reading

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