Vite Plugin which enables the import of Typed-Document-Nodes directly from .gql
/ .graphql
files, to allow for type-safe GraphQL implementations.
Fundamentally, this plugin allows you to import GraphQL DocumentNode
s 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.
schema.graphql
# [...]
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!
}
queries.graphql
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);
Install the package:
npm i --save-dev vite-plugin-typed-graphql
-
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 */)] });
-
Create a
schema.graphql
file containing your GraphQL schema in the root directory of your project (the path can be adjusted via the options) -
Check your
package.json
build script. Iftsc
(orvue-tsc
) is run beforevite build
you have to make surebuild-gql-declarations
runs beforetsc
.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" },
-
Although it is not necessary, we also recommend adding the following lines to your
.gitignore
:*.gql.d.ts *.graphql.d.ts
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.
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.
Type: String
Default: ./schema.graphql
Path to your schema file.
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.
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.
Type: String
Default: 'unknown'
Allows you to override the type that unknown scalars will have.
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'
},
}
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.