Migrating to typecscript-operations and client-preset 6.0

What’s new?

typescript-operations and client-preset v6.0 come with a major overhaul of type generation and config for better DX.

1. Type generation and usage changes
2. Configuration and dependency changes
3. Other bug fixes and quality of life improvements

For the most important changes, read the Breaking changes section.

For a full list of changes, see the CHANGELOG.

Installation

Install the new versions of official plugins that are in your dependencies:

npm i -D @graphql-codegen/cli@latest @graphql-codegen/typescript-operations@latest @graphql-codegen/client-preset@latest

pnpm add -D @graphql-codegen/cli@latest @graphql-codegen/typescript-operations@latest @graphql-codegen/client-preset@latest

yarn add --dev @graphql-codegen/cli@latest @graphql-codegen/typescript-operations@latest @graphql-codegen/client-preset@latest

bun add --dev @graphql-codegen/cli@latest @graphql-codegen/typescript-operations@latest @graphql-codegen/client-preset@latest

Migration

client-preset

client-preset already applies the recommended setup, you won’t have to make any changes to default config:

const config: CodegenConfig = {
  generates: {
    'src/gql/': {
      preset: 'client'
    }
  }
}

typescript-operations

typescript-operations can be used in a variety of custom setup, this section aims to explain the changes in the most popular setup.

One-file setup

This setup generates all base Input+Enum types and operation types into one file. Previously, this setup required typescript plugin but in the new version, you can remove typescript plugin as typescript-operations works by itself now.

const config: CodegenConfig = {
  generates: {
    'src/graphql/types.generated.ts': {
      plugins: ['typescript', 'typescript-operations'],
      plugins: ['typescript-operations']
    }
  }
}

Multi-file setup

Some repos may have multiple Codegen projects, each generating types for operations within its scope. In such cases, users may want to re-use the base Input+Enum types generated by typescript plugin with import-types preset:

const config: CodegenConfig = {
  generates: {
    'src/shared/base-types.generated.ts': {
      plugins: ['typescript']
    },
    'src/project-1/types.generated.ts': {
      documents: 'src/project-1/**/*.graphql.ts',
      preset: 'import-types',
      plugins: ['typescript-operations'],
      presetConfig: {
        typesPath: '../shared/base-types.generated.ts'
      }
    },
    'src/project-2/types.generated.ts': {
      documents: 'src/project-2/**/*.graphql.ts',
      preset: 'import-types',
      plugins: ['typescript-operations'],
      presetConfig: {
        typesPath: '../shared/base-types.generated.ts'
      }
    }
  }
}

Now, it is simpler to do this with typescript-operations as it supports this approach using its own config:

const config: CodegenConfig = {
  generates: {
    'src/shared/base-types.generated.ts': {
      documents: 'src/**/*.graphql.ts' // Parses all files with GraphQL documents to generate Enum+Input types that are used by every project
      plugins: ['typescript-operations'],
      config: {
        generateOperationTypes: false, // `generateOperationTypes:false` means only Input, Enum and shared utility types are generated
      }
    },
    'src/project-1/types.generated.ts': {
      documents: 'src/project-1/**/*.graphql.ts', // Only parses GraphQL documents within project-1's scope
      plugins: ['typescript-operations'],
      config: {
        importSchemaTypesFrom: 'src/shared/base-types.generated.ts', // this path is relative to Codegen config location (unlike `typesPath` in the old setup)
      }
    },
    'src/project-2/types.generated.ts': {
      documents: 'src/project-2/**/*.graphql.ts', // Only parses GraphQL documents within project-2's scope
      plugins: ['typescript-operations'],
      config: {
        importSchemaTypesFrom: 'src/shared/base-types.generated.ts',
      },
    }
  }
}

Breaking changes

1. Object types are no longer generated

Previously, Object types from the schema are generated (via the typescript plugin), for example:

// Example of a schema User Object type being previously generated
export type User = {
  __typename?: 'User'
  id: Scalars['ID']['output']
  name: Scalars['String']['output']
}

These types contain all the fields from the schema. It’s expected in GraphQL operations to not fetch all fields in practice so these types should never be used. However, they are often accidentally used in application code because they are generated.

Now, Object types are no longer generated. Operation types (Variables and Result) are generated based on fields in the documents so these should always be used for client types.

If you need schema types for any reasons, please generate them using typescript plugin into a separate file.

2. Args types are no longer generated

Args types are only used for server use cases, so they are no longer generated for client use cases.

3. Scalar types are no longer generated as re-useable type

Previously, Scalar types from the schema are generated into an object and re-used in Variables types:

// All native and custom scalars found in the schema were previously generated
export type Scalars = {
  ID: { input: string | number; output: string }
  String: { input: string; output: string }
  Boolean: { input: boolean; output: boolean }
  Int: { input: number; output: number }
  Float: { input: number; output: number }
}

Now, scalars in Input and Variables types are inlined (similar to Result types) to avoid using Scalar utility type:

export type Scalars = {
  ID: { input: string | number; output: string }
  String: { input: string; output: string }
  Boolean: { input: boolean; output: boolean }
  Int: { input: number; output: number }
  Float: { input: number; output: number }
}
 
export type UserInput = {
  id: Scalars['ID']['input']
  id: string | number
}
 
export type UserVariables = Exact<{
  id: Scalars['ID']['input']
  id: string | number
}>

4. Input and Enum types are only generated if used in documents

Previously, all Input and Enum types are generated even if they are not used. This could increase bundle size when Enums that incur runtime are used e.g. when native TypeScript enum or const enum are used. Now, only Input and Enum types used in operations are generated.

5. __typename is only generated if used in documents

Previously, __typename in Results is generated as optional by default, even when it is not requested:

query User {
  user {
    # Note: __typename is not in the selection set
    id
  }
}

Previously, the above operation resulted in a type with optional __typename:

export type UserQuery = {
  user: {
    __typename?: 'User'
    id: string
  }
}

Now, __typename will not be generated by default, if it is not in the selection set:

export type UserQuery = {
  user: {
    __typename?: 'User'
    id: string
  }
}

6. Document field types are generated to correctly match runtime expectation

Previously, nullable fields in Results are generated as optional by default:

export type UserQuery = {
  user: {
    age?: string | null
  }
}

Now, nullable fields in Results are never optional (except in some cases e.g. when @defer, @skip or @include are used)

export type UserQuery = {
  user: {
    age?: string | null
    age: string | null
  }
}

7. Enum config options are consolidated and change of default value

Previously, there were 4 boolean options to set which Enum variant to generate. However, when used together, the options override one other, so the behaviour is unexpected and confusing for both users and maintainers. In the new version, enumType is the only config option to use. The default has also been changed to string-literal since that is the option which does not incur runtime cost.

8. avoidOptionals option is updated to only handle operation types

Previously, avoidOptionals is shared with typescript plugin. As the result, some inner options do not affect operation types (such as avoidOptionals.resolvers, avoidOptionals.query, avoidOptionals.mutation, avoidOptionals.subscription).

Now, there are only 3 inner options, and when turned on, each forces the respective use case to pass in non-optional value.

• avoidOptionals.variableValue
• avoidOptionals.inputValue
• avoidOptionals.defaultValue

Note that the default is false, and you can still use avoidOptionals:true to turn on all options, without having to set each one individually.

9. preResolveTypes option is removed

preResolveTypes option is used to generate Result types inline (preResolveTypes:false) or use the ones generated by the typescript plugin (preResolveTypes:true). This is bad because (1) it adds dependency to the typescript plugin, (2) true and false have no functional difference to users, therefore (3) keeping this option doubles the maintenance overhead with no real benefits.

preResolveTypes:true is the default (and very stable) for a long time and should be used by majority of users by now. So, removing this option makes sense for us, but if you are seeing problems, please create an issue here.

10. Legacy utility types are removed

The following utility types have been removed:

• Maybe: used to handle nullability types of fields in Result. However, field types have been pre-resolved and inlined for a long time, so this option is no longer needed.
• InputMaybe: used to handle nullability types of Input. Input types are now inlined, so this option is longer needed.
• MakeOptional, MakeMaybe and MakeEmpty: used to handle preResolveTypes:false. However, preResolveTypes has been removed, so these options are no longer needed.

11. Make unknown the default type instead of any for custom scalars

Previously, custom Scalars default type was any which bypasses typecheck.

Now, We are making the default type unknown to ensure data is handled carefully by users.

12. Make string | number the default type for the native ID scalar

Previously, default Scalar type was being shared between client and server plugins (via the typescript plugin dependency). This means it was not possible to set the default for client as it would complicate the server config, and vice versa. See this PR for more details.

Now, there is no longer a dependency. So, we can set the default type as string | number which is the correct type for the client use case. For more details on how Scalar coercion works here, please read The Complete GraphQL Scalar Guide.