Vite Plugin Typed GraphQL

Vite Plugin which enables the import of Typed-Document-Nodes directly from .gql / .graphql files, to allow for type-safe GraphQL implementations.

How it works

Fundamentally, this plugin allows you to import GraphQL DocumentNodes from .gql / .graphql files, but it has a few more tricks up its sleeve.

Supplied with a GraphQL schema, it can automatically generate type declarations (.d.ts) files alongside all included GraphQL files, to allow type-safe Queries and Mutations.

Usage

# [...]

type User {
    """
    The username used to login.
    """
    login: String!
  
    # [...]
}

type Query {
    # [...]

    """
    Lookup a user by login.
    """
    user(login: String!): User

    """
    The currently authenticated user.
    """
    viewer: User!
}

query User($username: String!) {
    user(login: $username) {
        login
    }
}

query Viewer {
    viewer {
        login
    }
}

import { request } from 'graphql-request';
import { User, Viewer } from './queries.graphql';

const ENDPOINT = 'https://api.github.com/graphql';

// @ts-expect-error | This will error, because username has to be of type string
request(ENDPOINT, User, { username: 3 });

const { viewer } = await request(ENDPOINT, Viewer);

// @ts-expect-error | This will error, because unknown_field does not exist on user
console.log(viewer.unknown_field);

console.log(viewer.login);

Installation

Install the package:

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

Setup

1. Add the plugin to the Vite config:

   // vite.config.ts
   
   import { defineConfig } from 'vite';
   import typedGraphQL from 'vite-plugin-typed-graphql';
   
   export default defineConfig({
       plugins: [typedGraphQL(/* See below for list of options */)]
   });

2. Create a schema.graphql file containing your GraphQL schema in the root directory of your project (the path can be adjusted via the options)

3. Check your package.json build script. If tsc (or vue-tsc) is run before vite build you have to make sure build-gql-declarations runs before tsc.

   For example in a Vanilla Typescript project:

      "scripts": {
        "dev": "vite",
   -    "build": "tsc && vite build",
   +    "build": "build-gql-declarations && tsc && vite build",
        "preview": "vite preview"
      },

   or for a Vue Typescript project:

      "scripts": {
        "dev": "vite --host",
        "build": "run-p type-check build-only",
        "build-only": "vite build",
   -    "type-check": "vue-tsc --noEmit",
   +    "type-check": "build-gql-declarations && vue-tsc --noEmit",
        "preview": "vite preview"
      },

4. Although it is not necessary, we also recommend adding the following lines to your .gitignore:

   *.gql.d.ts
   *.graphql.d.ts

Options

exclude

Type: String | Array[...String]
Default: null

A minimatch pattern, or array of patterns, which specifies the files in the build the plugin should ignore. By default no files are ignored.

include

Type: String | Array[...String]
Default: null

A minimatch pattern, or array of patterns, which specifies the files in the build the plugin should operate on. By default all files are targeted.

schemaPath

Type: String
Default: ./schema.graphql

Path to your schema file.

generateDeclarations

Type: Boolean
Default: true

If true, instructs plugin to generate type declaration files next to included .graphql / .gql files, to allow for type-safe GraphQL queries / mutations.