{"id":22680,"library":"vite-plugin-graphql-codegen","title":"vite-plugin-graphql-codegen","description":"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.","status":"active","version":"3.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/danielwaltz/vite-plugin-graphql-codegen","tags":["javascript","graphql","codegen","graphql-codegen","graphql-code-generator","vite","vite-plugin","vite-plugin-graphql-codegen","typescript"],"install":[{"cmd":"npm install vite-plugin-graphql-codegen","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-graphql-codegen","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-graphql-codegen","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency - core codegen library that handles code generation logic","package":"@graphql-codegen/cli","optional":false},{"reason":"Peer dependency - required by @graphql-codegen/cli for parsing and executing GraphQL operations","package":"graphql","optional":false},{"reason":"Peer dependency - plugin only works within a Vite project, provides dev server and build hooks","package":"vite","optional":false}],"imports":[{"note":"Default export; CommonJS require works in CJS environments but ESM is recommended for Vite plugin usage.","wrong":"const codegen = require('vite-plugin-graphql-codegen')","symbol":"default","correct":"import codegen from 'vite-plugin-graphql-codegen'"},{"note":"Named export available as an alternative to default; useful for explicit named imports.","wrong":"import codegen from 'vite-plugin-graphql-codegen/vitePluginGraphqlCodegen'","symbol":"vitePluginGraphqlCodegen","correct":"import { vitePluginGraphqlCodegen } from 'vite-plugin-graphql-codegen'"},{"note":"TypeScript only - import type to avoid runtime inclusion. PluginOptions is not a value export.","wrong":"import { PluginOptions } from 'vite-plugin-graphql-codegen'","symbol":"PluginOptions","correct":"import type { PluginOptions } from 'vite-plugin-graphql-codegen'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport codegen from 'vite-plugin-graphql-codegen';\n\nexport default defineConfig({\n  plugins: [\n    codegen({\n      // Optional: override codegen config for specific triggers\n      configOverrideOnStart: {\n        generates: {\n          'src/generated/graphql.ts': {\n            documents: './src/**/*.graphql',\n            schema: 'https://api.example.com/graphql',\n            plugins: ['typescript', 'typescript-operations'],\n          },\n        },\n      },\n      // Skip codegen during CI build\n      skip: (context) => context.trigger === 'build' && process.env.CI === 'true',\n    }),\n  ],\n});","lang":"typescript","description":"Basic setup of vite-plugin-graphql-codegen in vite.config.ts with config override and conditional skip."},"warnings":[{"fix":"Update Vite and @graphql-codegen/cli to compatible versions.","message":"vite-plugin-graphql-codegen v3 requires Vite >=2.7.0 and @graphql-codegen/cli >=1.0.0. Older versions may not work.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade @graphql-codegen/cli to v6 or later.","message":"v3.7.0 drops support for @graphql-codegen/cli v5 and earlier. Checking compatibility issues with the codegen config.","severity":"breaking","affected_versions":">=3.7.0"},{"fix":"Migrate to using 'config' or 'configOverride' option, or a separate codegen config file.","message":"The 'schema' and 'documents' options (in versions <1.4.0) are deprecated; use 'configOverride' or a codegen config file instead.","severity":"deprecated","affected_versions":"<3.0.0"},{"fix":"Set runOnStart: false if you only want codegen on file changes.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Set throwOnStart: false to continue dev server even if initial codegen fails.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Use async/await or return a boolean directly.","message":"The 'skip' option callbacks can be async; ensure they return a boolean or Promise<boolean> or codegen might error.","severity":"gotcha","affected_versions":">=3.9.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run npm install vite-plugin-graphql-codegen @graphql-codegen/cli graphql vite","cause":"Plugin not installed or missing peer dependencies.","error":"Cannot find module 'vite-plugin-graphql-codegen' or its corresponding type declarations."},{"fix":"Run npm install @graphql-codegen/cli@latest","cause":"v3.7.0+ requires @graphql-codegen/cli v6 or later.","error":"Error: @graphql-codegen/cli version 5 is not supported. Please upgrade to >=6.0.0."},{"fix":"Use import codegen from 'vite-plugin-graphql-codegen' instead of { codegen }.","cause":"Importing the plugin incorrectly (e.g., using named import instead of default).","error":"TypeError: codegen is not a function"},{"fix":"Check your codegen.yml or configOverride for errors, ensure schema URL is reachable and documents pattern matches files.","cause":"Codegen configuration (schema, documents, or plugins) are misconfigured.","error":"Error: GraphQL Code Generator failed with 1 error(s). TypeScript errors found."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}