vite-plugin-graphql-loader

A Vite plugin for loading GraphQL .gql and .graphql files, based on graphql-tag/loader

This package doesn't generate TypeScript definitions from the queries and fragments - see vite-plugin-graphql-codegen if you require this.

Install

yarn add -D vite-plugin-graphql-loader graphql

or

npm i --save-dev vite-plugin-graphql-loader graphql

Usage

In vite.config.ts or vite.config.js:

import { defineConfig } from "vite";
import graphqlLoader from "vite-plugin-graphql-loader";

export default defineConfig({
    plugins: [graphqlLoader()],
});

Now you can import queries from .gql or .graphql files.

example.graphql:

#import "./ExampleImport.graphql"

fragment ExampleFragment on example {
    id
    name
}

query ExampleQuery {
    example {
        ...ExampleFragment
        ...ExampleImport
    }
}

example.js:

import ExampleQuery, { ExampleFragment } from "./example.graphql";

If you have multiple queries in the same file, import them like this:

import { FirstQuery, SecondQuery } from "./example.graphql";

TypeScript

If you are using TypeScript, you will have to declare .gql or .graphql files.

Create graphql.d.ts anywhere in your source directory:

declare module "*.gql";
declare module "*.graphql";

Alternatively, for full type information (replacing .gql with .graphql depending on what you use):

declare module "*.gql" {
    const Query: import("graphql").DocumentNode;
    export default Query;
    export const _queries: Record<string, import("graphql").DocumentNode>;
    export const _fragments: Record<string, import("graphql").FragmentDefinitionNode>;
}

And then import fragments and queries like so in order to type them as DocumentNode and FragmentDefinitionNode objects.

import Document, { _queries, _fragments } from "./example.graphql";
console.log(Document); // Has type `DocumentNode`
console.log(_queries.ExampleQuery); // Has type `DocumentNode`
console.log(_fragments.ExampleFragment); // Has type `FragmentDefinitionNode`

Changelog

v5.1.1:

• Fix: escape backslashes in the source before backticks and ${ so loc.source.body round-trips a GraphQL document containing \ characters (e.g. a String default with a \n escape). Previously the emitted template literal interpreted the backslash sequences and body !== source.
• Fix: use Object.create(null) for the deduplication map in vitePluginGraphqlLoaderUniqueChecker and for definitionRefs in vitePluginGraphqlLoaderExtractQuery. A fragment named constructor, toString, or any other Object.prototype property name was previously dropped on first occurrence because the plain-object lookup returned a truthy inherited value.
• Fix: throw a clear error at transform time when a definition uses a reserved identifier name (_gql_doc, _gql_source, _queries, _fragments). Previously these names emitted duplicate const declarations and the module failed to load at runtime.
• Release workflow now runs format:check and the integration test, matching the regular CI matrix.
• Drop redundant .npmignore (package.json#files whitelist is authoritative) and dead package:bump / package:publish scripts (superseded by the tag-driven release workflow).

v5.1.0:

• Security: validate #import paths and reject those containing quotes, backticks, backslashes, or newlines (could otherwise inject code into the emitted ESM via a crafted path).
• Fix: escape ${ in emitted template literals so GraphQL sources containing ${...} (e.g. in comments/descriptions) no longer interpolate into the emitted code.
• Fix: emit LF newlines so source maps remain accurate on Windows (the previous os.EOL replace happened after MagicString computed its byte offsets, desyncing the sourcemap on CRLF systems).
• Fix: match .gql / .graphql IDs with ?query suffixes (Vite emits these for some module-graph operations).
• Fix: extractQuery now throws a clear error when the named operation is not in the document (previously produced definitions: [undefined]).
• Fix: loc.source is now reattached via separate emitted statements rather than UUID-placeholder string replacement (no collision risk if a GraphQL source happened to contain the sentinel).
• Annotate the plugin's return type as Vite's Plugin for consumer DX.
• Add prepublishOnly script (build && test:run), engines.node (^20.19.0 || >=22.12.0).
• Flatten dist layout: dist/index.js (was dist/src/index.js). Exports field updated — no consumer-facing change via the package entrypoint.
• CI on GitHub Actions (lint, typecheck, tests, build, integration test), tag-triggered release with npm provenance via Trusted Publishing and auto-generated GitHub Releases.

v5.0.0:

• Breaking: graphql is now a peer dependency. If you don't already have it installed, run npm i graphql.
• Added vite as a peer dependency with support for vite 5, 6, 7, and 8.
• Switched build tooling to tsgo (TypeScript 7 native compiler), oxlint, and oxfmt.
• Updated all dependencies to latest versions.
• Added integration test suite covering all import styles and query patterns.
• Fixed named import syntax (#import ... from ...) not being published in v4.0.4 (fixes #12).

v4.0.1:

• Allow passing sourceMapOptions when initializing the plugin to configure how the source map is generated (see options here). noSourceMap can alternatively be used to disable source map generation. For example, to enable more detailed source maps:

import graphqlLoader from "vite-plugin-graphql-loader";
graphqlLoader({ sourceMapOptions: { hires: true } });

v4.0.0:

• Added source-map generation. Can be disabled by initializing with graphqlLoader({noSourceMap: true}).
• Refactored code generation to be more maintainable, added more test cases.
• Migrated from yarn to bun.

v3.0.1:

• Switched await import statements to top-level import statements (fixes #5 - Top-level await is not available error).
• Added _queries and _fragments for improved module declaration types.
• Updated snippets to be defined in TypeScript and then stringified.

v3.0.0:

• Moved from CJS to ESM, inline with Vite 5.0's CJS deprecation. If you are using CommonJS, continue using v2.0 of this package. If you have "type": "module", in your package.json then it should work as expected.