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.

codegenPluginConfigs

Type: Object (see here)
Default: {}

Config to pass to the typescript plugin of GraphQL codegen.
This allows you to set options like TS types for scalars. See here for a detailed list of options.

strictScalars

Type: Boolean
Default: false

Makes scalars strict.

If scalars are found in the schema that are not defined in scalars an error will be thrown during codegen.

defaultScalarType

Type: String
Default: 'unknown'

Allows you to override the type that unknown scalars will have.

scalars

Type: { [name: string]: string | { input: string, output: string } }
Default: {}

Extend or override the built-in scalars and custom GraphQL scalars to a custom type.

Example:

{
    UUID: 'string',
    DateTime: {
        input: 'Date | string',
        output: 'string'
    },
}

codegenPluginConfigs

Type: Object
Default: {}

Configs to pass to the GraphQL-Codegen plugins. Has to properties:

• typescript for typescript plugin config (see documentation)
• typescriptOperations for TypeScript operations plugin (see documentation)

[!NOTE] strictScalars, defaultScalarType, and scalars in both typescript and typescriptOperations configs will be overridden by the options in this plugin.