{"id":22681,"library":"vite-plugin-graphql-loader","title":"vite-plugin-graphql-loader","description":"A Vite plugin for loading GraphQL .gql and .graphql files, based on the webpack graphql-tag/loader. Current version 5.0.1 requires graphql ^16.0.0 and supports Vite 5, 6, 7, and 8 as peer dependencies. Ships TypeScript types, provides default and named imports of DocumentNode objects, and handles fragment deduplication and source maps. Unlike vite-plugin-graphql-codegen, it does not generate TypeScript definitions from queries.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/0x31/vite-plugin-graphql-loader","tags":["javascript","graphql","graphql-tag","vite","vite-plugin","typescript"],"install":[{"cmd":"npm install vite-plugin-graphql-loader","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-graphql-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-graphql-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required at runtime to operate on DocumentNode objects; breaking change in v5.0.0 moved it from dependency to peer.","package":"graphql","optional":false},{"reason":"Peer dependency; the plugin is designed to work with Vite 5, 6, 7, or 8.","package":"vite","optional":false}],"imports":[{"note":"The plugin is ESM-only since v3.0.0. CommonJS require will fail with newer versions. Use import or dynamic import.","wrong":"const graphqlLoader = require('vite-plugin-graphql-loader')","symbol":"default (graphqlLoader)","correct":"import graphqlLoader from 'vite-plugin-graphql-loader'"},{"note":"Default import yields the first query/operation. Named imports for specific queries/fragments require explicit syntax see next entry.","wrong":"import { ExampleQuery } from './example.graphql'","symbol":"default import from .graphql file","correct":"import ExampleQuery from './example.graphql'"},{"note":"Named imports correspond to the operation names defined in the GraphQL file. Default export still exists for the first operation.","wrong":"import { MyQuery } from './example.graphql'","symbol":"named imports from .graphql file","correct":"import { MyQuery, MyFragment } from './example.graphql'"},{"note":"Underscore-prefixed exports provide maps of all queries and fragments by name, typed via the module declaration pattern.","wrong":"","symbol":"_queries and _fragments","correct":"import Doc, { _queries, _fragments } from './example.graphql'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport graphqlLoader from 'vite-plugin-graphql-loader';\n\nexport default defineConfig({\n  plugins: [graphqlLoader()],\n});\n\n// App.ts\nimport MyQuery from './query.graphql';\nimport { useQuery } from '@apollo/client';\n\nfunction App() {\n  const { loading, data } = useQuery(MyQuery);\n  return <div>{JSON.stringify(data)}</div>;\n}","lang":"typescript","description":"Shows how to install and configure the plugin, then import a GraphQL file and use it with Apollo Client."},"warnings":[{"fix":"Run npm install graphql or yarn add graphql.","message":"graphql is now a peer dependency in v5.0.0. Must be installed separately.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Use import syntax or update to a modern Node version with ESM support. If you need CommonJS, pin to version 2.0.0.","message":"Switched from CommonJS to ESM only starting v3.0.0. CJS projects must stay on v2.x.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure vite is installed and version matches one of the supported ranges.","message":"Vite peer dependency added in v5.0.0. Plugin only tested with Vite 5, 6, 7, and 8.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Use named exports for specific operations or rely on _queries export for robust access.","message":"Default export of a .graphql file is the first operation, not necessarily the first query if a fragment is defined first.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure fragment names are unique across all imported files to avoid deduplication issues.","message":"Fragments imported via #import are deduplicated, but multiple definitions of the same fragment can cause unexpected behavior if not careful.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Upgrade to v3.0.1 or later, or set a modern output target.","cause":"Using a version before 3.0.1 with older bundlers or targets that don't support top-level await.","error":"Top-level await is not available in the configured target environment"},{"fix":"Run npm install graphql or yarn add graphql.","cause":"graphql is not installed (required as peer dependency since v5.0.0).","error":"Module not found: Error: Can't resolve 'graphql'"},{"fix":"Switch to import syntax or downgrade to v2.0.x.","cause":"Using CommonJS require() with v3.0.0+ which is ESM-only.","error":"ERR_REQUIRE_ESM: require() of ES Module from ... not supported"},{"fix":"Use import graphqlLoader from 'vite-plugin-graphql-loader' in an ESM context.","cause":"CommonJS default import mismatch; attempted const { default: graphqlLoader } = require(...) incorrectly.","error":"The requested module 'vite-plugin-graphql-loader' does not provide an export named 'default'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}