vite-plugin-graphql-codegen

3.9.0 verified Mon Apr 27 auth: no javascript

Zero-config Vite plugin that leverages the Vite file watcher to run GraphQL Code Generator programmatically, eliminating the need for a separate watch process. Version 3.9.0 supports Vite 2.7–8, GraphQL 14–16, and @graphql-codegen/cli 1–6. Key differentiators: no CLI wrapper needed, integrates tightly with Vite's dev server and build pipeline, offers fine-grained control over when codegen runs (start/build/watch), and supports multi-project configurations. Ships TypeScript types. Released continuously since 2020, with active maintenance including support for Vite 8.

Common errors

error Cannot find module 'vite-plugin-graphql-codegen' or its corresponding type declarations. ↓

cause Plugin not installed or missing peer dependencies.

fix

Run npm install vite-plugin-graphql-codegen @graphql-codegen/cli graphql vite

error Error: @graphql-codegen/cli version 5 is not supported. Please upgrade to >=6.0.0. ↓

cause v3.7.0+ requires @graphql-codegen/cli v6 or later.

fix

Run npm install @graphql-codegen/cli@latest

error TypeError: codegen is not a function ↓

cause Importing the plugin incorrectly (e.g., using named import instead of default).

fix

Use import codegen from 'vite-plugin-graphql-codegen' instead of { codegen }.

error Error: GraphQL Code Generator failed with 1 error(s). TypeScript errors found. ↓

cause Codegen configuration (schema, documents, or plugins) are misconfigured.

fix

Check your codegen.yml or configOverride for errors, ensure schema URL is reachable and documents pattern matches files.

Warnings

breaking vite-plugin-graphql-codegen v3 requires Vite >=2.7.0 and @graphql-codegen/cli >=1.0.0. Older versions may not work. ↓

fix Update Vite and @graphql-codegen/cli to compatible versions.

breaking v3.7.0 drops support for @graphql-codegen/cli v5 and earlier. Checking compatibility issues with the codegen config. ↓

fix Upgrade @graphql-codegen/cli to v6 or later.

deprecated The 'schema' and 'documents' options (in versions <1.4.0) are deprecated; use 'configOverride' or a codegen config file instead. ↓

fix Migrate to using 'config' or 'configOverride' option, or a separate codegen config file.

gotcha Codegen may run multiple times on startup due to Vite's file watcher detecting changes. The plugin provides 'runOnStart: false' option to disable initial run. ↓

fix Set runOnStart: false if you only want codegen on file changes.

gotcha If codegen config file is large, the plugin may cause startup delay. Use 'throwOnStart: false' to avoid build failure if codegen fails during dev start. ↓

fix Set throwOnStart: false to continue dev server even if initial codegen fails.

gotcha The 'skip' option callbacks can be async; ensure they return a boolean or Promise<boolean> or codegen might error. ↓

fix Use async/await or return a boolean directly.

Install

npm install vite-plugin-graphql-codegen

yarn add vite-plugin-graphql-codegen

pnpm add vite-plugin-graphql-codegen

Imports

default
wrong
```
const codegen = require('vite-plugin-graphql-codegen')
```
correct
```
import codegen from 'vite-plugin-graphql-codegen'
```
Default export; CommonJS require works in CJS environments but ESM is recommended for Vite plugin usage.

vitePluginGraphqlCodegen

wrong

import codegen from 'vite-plugin-graphql-codegen/vitePluginGraphqlCodegen'

correct

import { vitePluginGraphqlCodegen } from 'vite-plugin-graphql-codegen'

Named export available as an alternative to default; useful for explicit named imports.

PluginOptions

wrong

import { PluginOptions } from 'vite-plugin-graphql-codegen'

correct

import type { PluginOptions } from 'vite-plugin-graphql-codegen'

TypeScript only - import type to avoid runtime inclusion. PluginOptions is not a value export.

Quickstart

Basic setup of vite-plugin-graphql-codegen in vite.config.ts with config override and conditional skip.

// vite.config.ts
import { defineConfig } from 'vite';
import codegen from 'vite-plugin-graphql-codegen';

export default defineConfig({
  plugins: [
    codegen({
      // Optional: override codegen config for specific triggers
      configOverrideOnStart: {
        generates: {
          'src/generated/graphql.ts': {
            documents: './src/**/*.graphql',
            schema: 'https://api.example.com/graphql',
            plugins: ['typescript', 'typescript-operations'],
          },
        },
      },
      // Skip codegen during CI build
      skip: (context) => context.trigger === 'build' && process.env.CI === 'true',
    }),
  ],
});