GraphQL Codegen Update, November 2026 - CLI v8.0 and new plugin majors

Eddy Nguyen
Eddy Nguyen
On this page

@graphql-codegen/cli v8.0 and new plugin majors are now available, bumping minimum supported versions and removing deprecated options and APIs.

  • Minimum Node.js is now >=22.18.0, and graphql below v16 is no longer supported
  • @graphql-tools/* dependencies and graphql-config move to their latest majors
  • emitLegacyCommonJSImports is removed in favour of importExtension
  • generates output entries can be arrays, but only the first configuration is used
  • Plugin validate now matches the plugin function signature

What’s in v8?

Most of this release is housekeeping: dropping old Node.js and graphql versions we no longer test against, picking up the latest @graphql-tools and graphql-config majors, and removing options and types that had been deprecated or silently broken for a while.

A couple of changes can still change the shape of your generated code - notably the code-file-loader@9 document pluck default and the emitLegacyCommonJSImports removal below - so a few of the changes do need action on your side.

Breaking changes

Node.js and graphql

The new @graphql-tools/* majors require Node.js >=22.18.0, so the CLI and all official packages raise their engines.node to match. graphql v14 and v15 are no longer supported - the peer range is now ^16.0.0 || ^17.0.0.

@graphql-tools/* and graphql-config updates

All @graphql-tools/* dependencies move together and now require @graphql-tools/utils@^13, and graphql-config is updated to v6. If you have custom loaders, plugins, or graphql-config extensions, make sure they’re compatible with these versions.

emitLegacyCommonJSImports is replaced by importExtension

The emitLegacyCommonJSImports config option and --emit-legacy-common-js-imports CLI flag are removed. importExtension (or --import-extension) is now the only way to control the extension of relative imports:

codegen.ts
 const config: CodegenConfig = {
   config: {
-    emitLegacyCommonJSImports: false
+    importExtension: '.js'
   }
 }

If you never set emitLegacyCommonJSImports: false, there’s nothing to change.

config.generates is now handled correctly as an array

The previous typing suggested an array could be used for a generates output, but it always failed at runtime. Now, it handles the first element gracefully. In the future, it will handle elements sequentially - see issue #10943.

Plugin API changes

A few changes affect custom plugin authors:

  • validate now receives { outputFile, allPlugins, pluginContext } as its fourth argument, matching the plugin function signature, instead of separate positional arguments.
  • generate() is typed as Promise<FileOutput[] | void> instead of collapsing to any, so narrow the result with Array.isArray(result) before indexing it.
  • plugin-helpers removes isOutputConfigArray, isConfiguredOutput, and normalizeImportExtension, and normalizeOutputParam now always returns ConfiguredOutput[].

Read the full v8 migration guide for every breaking change, with before/after snippets.

Upgrading

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

Resources

Explore

Dive deeper into related topics.

GraphQL

Introducing @graphql-tools/external-fragment-loader

Igor Kusakov
GraphQL

Hive Gateway: Local Subgraph Development Just Got Easier

Jeff Dolle

Get your API game right.