Migrating from GraphQL Code Generator

GraphQL Code Generator is a great tool for generating code from GraphQL schema and operations. Basically it has the same goal as nitrogql. This page guides you how to migrate from GraphQL Code Generator to nitrogql.

GraphQL Code Generator has a couple of presets that control how TypeScript code is generated. nitrogql's approach is similar to the near-operation-file preset. This preset was the recommended preset while GraphQL Code Generator was in v2.

While GraphQL Code Generator has changed their recommended preset to the client preset, nitrogql still endorses the idea of the near-operation-file preset.

Prerequisites

This guide assumes that you are using GraphQL Code Generator under the following conditions:

You are using the near-operation-file preset.
You write your GraphQL operations in .graphql files, not inside .ts files.

If you diverge from these conditions, you need to first migrate to these conditions before migrating to nitrogql.

😥 Generating resolver types is not supported in nitrogql yet. If you are using GraphQL Code Generator to generate resolver types, that part cannot be migrated to nitrogql for now.

Before migrating to nitrogql

Apart from the above fundamental differences, nitrogql has limited, opinionated set of configuration options. This means that some of the configuration options you used in GraphQL Code Generator may not be available in nitrogql.

While you stay with GraphQL Code Generator, you first need to adjust its usage to be compatible with nitrogql.

Use `TypedDocumentNode`

GraphQL Code Generator has a couple of plugins that generate TypeScript code from GraphQL operations. For example, typescript-react-apollo generates React Hooks for each GraphQL operation which use Apollo Client under the hood.

However, nitrogql only supports TypedDocumentNode-based code generation. Don't worry, TypedDocumentNode can be used with any popular UI library or GraphQL client library. That's why GraphQL Code Generator also recommends using TypedDocumentNode.

Therefore, you need to migrate to the typed-document-node plugin. If you are not familiar with TypedDocumentNode, Episode #41 of graphql.wtf is a great resource to learn how to migrate to typed-document-node.

Before you can migrate to nitrogql, you need to be using only typescript-operations and typed-document-node plugins, not those library-specific ones.

Disable case conversion

Under the default settings, GraphQL Code Generator converts identifiers to PascalCase. For example, getUser is converted to GetUser and ENUM_VALUE is converted to EnumValue.

nitrogql does not do such case conversion by default. Therefore, the namingConvention option of the typescript-operations plugin should be set to keep. If you change the namingConvention option, you may also need to change TypeScript code accordingly.

# codegen.yml
config:
  namingConvention: keep

Set `enumsAsConst: true`

GraphQL Code Generator generates code from enums using TypeScript's enum syntax by default. However, nitrogql does not use that syntax. Instead, nitrogql uses plain union types.

This difference is not a big deal, but it may cause some incompatibility issues. Therefore, it is recommended to set enumsAsConst: true and solve any incompatibility issues before migrating to nitrogql.

# codegen.yml
config:
  enumsAsConst: true

Change output extension

By default, the near-operation-file preset generates foo.generated.ts next to foo.graphql. This means that if you want to import code generated from foo.graphql, you need to import foo.generated.ts:

// default setting of GraphQL Code Generator
import { fooQuery } from "./foo.generated";

On the other hand, nitrogql recommends to import directly from foo.graphql:

// after migrating to nitrogql
import { fooQuery } from "./foo.graphql";

For the ease of migration, adjust GraphQL Code Generator's configuration to generate foo.graphql.ts instead of foo.generated.ts. This can be done by setting extension: .graphql.ts in presetConfig.

After you change the extension, you need to update all import declarations to import from .graphql files instead of .generated files. Don't forget to update your.gitignore to ignore .graphql.ts files.

# codegen.yml
generates:
  src/:
    # ...
    presetConfig:
      extension: .graphql.ts

Adjust generated type names

GraphQL Code Generator and nitrogql have different naming conventions for generated types. Before migrating to nitrogql, adjust your code to match nitrogql's naming convention.

For example, when you have a query named GetUser, default output of GraphQL Code Generator and nitrogql are summarized as follows:

	GraphQL Code Generator	nitrogql
operation document object	`GetUserDocument`	`GetUserQuery`
operation result type	`GetUserQuery`	`GetUserResult`
operation variables type	`GetUserQueryVariables`	`GetUserVariables`

Note that Query in the table is substituted with Mutation or Subscription depending on the operation type.

You can adjust the names of result type and variables type with the following settings:

# GraphQL Code Generator config
config:
  omitOperationSuffix: true
  operationResultSuffix: Result

As is the case with other configuration changes, you need to update all TypeScript code that imports these types.

Name of the operation document object (GetUserDocument) still differ from nitrogql with the above setting. Since GraphQL Code Generator cannot exactly match the nitrogql behavior, we will guide you to configure nitrogql to match the current behavior of GraphQL Code Generator.

Migrating to nitrogql

Now you are ready to migrate to nitrogql!

🤯 If you are in a monorepo setting, adjust below instructions as explained in the monorepo guide.

Install nitrogql

First, install nitrogql and its dependencies.

npm install -D @nitrogql/cli

If you are using webpack, you also need to install appropriate webpack loader. Note that this also applies to Next.js projects.

npm install -D @nitrogql/graphql-loader

If you are using Rollup, you need to install appropriate Rollup plugin. Note that this also applies to Vite projects.

npm install -D @nitrogql/rollup-plugin

Create nitrogql config

Nitrogql's configuration file is either graphql.config.yaml or .graphqlrc.yaml at the root of your project. You might have already one depending on your GraphQL Code Generator configuration. Also, you can use .json or .js files instead of .yaml at your preference.

You can reuse schema and documents options from your GraphQL Code Generator configuration. Start by copying them to your nitrogql configuration file:

# graphql.config.yaml
schema: src/schema/*.graphql
documents: src/app/**/*.graphql

Note that any other nitrogql options are put under extensions.nitrogql object.

Configure schema output

One option you need to set is generate.schemaOutput. This option controls where the generated schema type definition is written to. Set it to the path to the file where you want to write the schema type definition to. This option corresponds to the typescript plugin of GraphQL Code Generator.

Also, if you are importing enums from the generated schema file, you need to set generate.emitSchemaRuntime to true. This is the default setting of GraphQL Code Generator, but nitrogql does not emit runtime enum definitions by default.

Example:

# GraphQL Code Generator configuration
generates:
  path/to/schema.ts:
    plugins:
      - typescript
    config:
      # ...

# corresponding nitrogql configuration (graphql.config.yaml)
schema: src/schema/*.graphql
documents: src/app/**/*.graphql
extensions:
  nitrogql:
    generate:
      schemaOutput: path/to/schema.ts
      emitSchemaRuntime: true

Configure operation output

Next, you need to configure generation of TypeScript code from GraphQL operations. This corresponds to the typescript-operations plugin of GraphQL Code Generator.

Without additional configuration, nitrogql generates TypeScript code next to each GraphQL operations files. This is the same architecture as GraphQL Code Generator's near-operation-file preset.

However, you need to adjust nitrogql's generate option so that you can use the generated code from your application in the same way as you did with GraphQL Code Generator.

Below is the nitrogql configuration for keeping the same behavior as your current settings.

schema: src/schema/*.graphql
documents: src/app/**/*.graphql
extensions:
  nitrogql:
    generate:
      schemaOutput: path/to/schema.ts
      emitSchemaRuntime: true
      # add below
      export:
        defaultExportForOperation: false
        variablesType: true
        operationResultType: true
      name:
        queryVariableSuffix: Document
        mutationVariableSuffix: Document
        subscriptionVariableSuffix: Document

Configure TypeScript

In order to use the generated code from your application, you might need to adjust TypeScript configuration to recognize the generated code.

In your tsconfig.json, set the allowArbitraryExtensions compiler option to true so that TypeScript lets you import .graphql files.

Note that this option is only available in TypeScript 5.0 or later. If you are using an older version of TypeScript, you can set nitrogql's generate.mode option to with-loader-ts-4.0.

Configure webpack loader or Rollup plugin

As the last step, you need to configure webpack loader or Rollup plugin so that they can load .graphql files.

If you are using webpack, add the following to your webpack configuration:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      // ...
      {
        test: /\.graphql$/,
        use: [
          {
            loader: "@nitrogql/graphql-loader",
            options: {
              // path to your nitrogql configuration file
              configFile: "./graphql.config.yaml",
            },
          },
        ],
      },
    ],
  },
};

If you are using Rollup, add the following to your Rollup configuration:

// rollup.config.js
import graphql from "@nitrogql/rollup-plugin";

export default {
  // ...
  plugins: [
    // ...
    graphql({
      // path to your nitrogql configuration file
      configFile: "./graphql.config.yaml",
      include: ["**/*.graphql"],
    }),
  ],
};

Using nitrogql CLI

After you migrate to nitrogql, you need to also migrate build scripts to use nitrogql CLI.

Basically, you need to replace graphql-codegen command with nitrogql generate.

Watch mode

nitrogql CLI does not have a watch mode for now. If you need a watch mode, you can use nodemon or chokidar-cli to watch GraphQL files and run nitrogql generate automatically.

For example, if you are using chokidar-cli, a command for watching GraphQL files and running nitrogql generate is as follows:

chokidar '**/*.graphql' --initial --command 'npx nitrogql generate'

🧺 Read Next: Configuration, CLI Usage