Skip to content

apollo-tooling.mdx

Latest commit

 

History

History
303 lines (244 loc) · 9.72 KB

apollo-tooling.mdx

File metadata and controls

303 lines (244 loc) · 9.72 KB
description Migrating from Apollo Tooling (apollo client:codegen) to GraphQL Code Generator. What has changed? How to migrate? What configuration options replace Apollo Tooling's behaviour?

import { Callout, Tabs } from '@theguild/components'

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:

<Tabs items={['Before', 'After']}> <Tabs.Tab>

npm uninstall apollo

</Tabs.Tab>

<Tabs.Tab>

npm i -D @graphql-codegen/cli @graphql-codegen/typescript-operations @graphql-codegen/near-operation-file-preset

</Tabs.Tab>

Required packages

Package Description
@graphql-codegen/cli Core CLI that runs the code generator
@graphql-codegen/typescript-operations Plugin that generates TypeScript types for GraphQL operations
@graphql-codegen/near-operation-file-preset Preset that places generated files next to their source operations 
{
  "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.

<Tabs items={['Before', 'After']}> <Tabs.Tab>

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

</Tabs.Tab>

<Tabs.Tab>

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**',
filePerOperation: true,
inGeneratesOnly: true,
},
plugins: ['typescript-operations'],
},
},
}

export default config
graphql-codegen

</Tabs.Tab>

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

{
  "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.

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:

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

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:

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