TypeScript React-Query

Usage Requirements

In order to use this GraphQL Codegen plugin, please make sure that you have GraphQL operations (query / mutation / subscription and fragment) set as documents: ... in your codegen.yml.

Without loading your GraphQL operations (query, mutation, subscription and fragment), you won't see any change in the generated output.

This plugin generates React-Query Hooks with TypeScript typings.

It extends the basic TypeScript plugins: @graphql-codegen/typescript, @graphql-codegen/typescript-operations - and thus shares a similar configuration.

Installation

typescript-react-query plugin version
Using yarn
yarn add -D @graphql-codegen/typescript-react-query

API Reference

fetcher

type: object | string

Customize the fetcher you wish to use in the generated file. React-Query is agnostic to the data-fetcing layer, so you should provide it, or use a custom one.

The following options are available to use:

  • 'fetch' - requires you to specify endpoint and headers on each call, and uses fetch to do the actual http call.
  • { endpoint: string, fetchParams: RequestInit }: hardcode your endpoint and fetch options into the generated output, using the environment fetch method. You can also use process.env.MY_VAR as endpoint or header value.
  • file#identifier - You can use custom fetcher method that should implement the exported ReactQueryFetcher interface. Example: ./my-fetcher#myCustomFetcher.
  • graphql-request: Will generate each hook with client argument, where you should pass your own GraphQLClient (created from graphql-request).

dedupeOperationSuffix

type: boolean default: false

Set this configuration to true if you wish to make sure to remove duplicate operation name suffix.

omitOperationSuffix

type: boolean default: false

Set this configuration to true if you wish to disable auto add suffix of operation name, like Query, Mutation, Subscription, Fragment.

operationResultSuffix

type: string default: ``

Adds a suffix to generated operation result type names

documentVariablePrefix

type: string default: ``

Changes the GraphQL operations variables prefix.

documentVariableSuffix

type: string default: Document

Changes the GraphQL operations variables suffix.

fragmentVariablePrefix

type: string default: ``

Changes the GraphQL fragments variables prefix.

fragmentVariableSuffix

type: string default: FragmentDoc

Changes the GraphQL fragments variables suffix.

optimizeDocumentNode

type: boolean default: true

If you are using documentNode: documentMode | documentNodeImportFragments, you can set this to true to apply document optimizations for your GraphQL document. This will remove all "loc" and "description" fields from the compiled document, and will remove all empty arrays (such as directives, arguments and variableDefinitions).

pureMagicComment

type: boolean default: false

This config adds PURE magic comment to the static variables to enforce treeshaking for your bundler.

scalars

type: ScalarsMap

Extends or overrides the built-in scalars and custom GraphQL scalars to a custom type.

namingConvention

type: NamingConvention default: pascal-case#pascalCase

Allow you to override the naming convention of the output. You can either override all namings, or specify an object with specific custom naming convention per output. The format of the converter must be a valid module#method. Allowed values for specific output are: typeNames, enumValues. You can also use "keep" to keep all GraphQL names as-is. Additionally you can set transformUnderscore to true if you want to override the default behavior, which is to preserves underscores.

typesPrefix

type: string default: ``

Prefixes all the generated types.

Usage Examples

config:
typesPrefix: I

typesSuffix

type: string default: ``

Suffixes all the generated types.

Usage Examples

config:
typesSuffix: I

skipTypename

type: boolean default: false

Does not add __typename to the generated types, unless it was specified in the selection set.

Usage Examples

config:
skipTypename: true

nonOptionalTypename

type: boolean default: false

Automatically adds __typename field to the generated types, even when they are not specified in the selection set, and makes it non-optional

Usage Examples

config:
nonOptionalTypename: true

Usage Examples#

Note: all generated hooks are just wrappers around react-query original functions. This codegen plugin just burns the generated TypeScript types into the operation, and provides flexibility to choose your fetcher.

Using default fetch#

By default, this plugin will generate a fetcher based on the environment global fetch definition.

schema: MY_SCHEMA_PATH
documents: './src/**/*.graphql'
generates:
./generates.ts:
plugins:
- typescript
- typescript-operations
- typescript-react-query
config:
fetcher: fetch

To use the generate hooks, import it, and then specify the endpoint and optionally fetchParams:

import { useMyQuery } from './generated';
export const MyComponent = () => {
const { status, data, error, isFetching } = useMyQuery({
endpoint: 'http://localhost:3000/graphql',
fetchParams: {
headers: {
'My-Header': 'XYZ',
},
},
});
};

Using fetch with Codegen configuration#

If you wish to avoid specifying endpoint and fetchParams on each hook usage, you can specify those in the codegen.yml file:

schema: MY_SCHEMA_PATH
documents: './src/**/*.graphql'
generates:
./generates.ts:
plugins:
- typescript
- typescript-operations
- typescript-react-query
config:
fetcher:
endpoint: 'http://localhost:3000/graphql'
fetchParams:
headers:
My-Header: SomeValue

And if you wish to have more control over the value, or even provide it in runtime, you can use environment variables:

schema: MY_SCHEMA_PATH
documents: './src/**/*.graphql'
generates:
./generates.ts:
plugins:
- typescript
- typescript-operations
- typescript-react-query
config:
fetcher:
endpoint: 'process.env.ENDPOINT'

You can even use a custom variable from your code, and add custom imports with add plugin:

schema: MY_SCHEMA_PATH
documents: './src/**/*.graphql'
generates:
./generates.ts:
plugins:
- add:
content: "import { endpointUrl, fetchParams } from './my-config';"
- typescript
- typescript-operations
- typescript-react-query
config:
fetcher:
endpoint: 'endpointUrl'
fetchParams: 'fetchParams'

The generated hooks doesn't require you to specify anything, you can just use it as-is:

import { useMyQuery } from './generated';
export const MyComponent = () => {
const { status, data, error, isFetching } = useMyQuery({});
};

Using graphql-request#

If you are using graphql-request, you can set fetcher to graphql-request, and then the generated React Hook will expect you to pass the GraphQLClient instance (created by graphql-request library).

schema: MY_SCHEMA_PATH
documents: './src/**/*.graphql'
generates:
./generates.ts:
plugins:
- typescript
- typescript-operations
- typescript-react-query
config:
fetcher: graphql-request

And the, while using, provide your client instance:

import { useMyQuery } from './generated';
import { client } from './my-graphql-request-client';
export const MyComponent = () => {
const { status, data, error, isFetching } = useMyQuery(client, {});
};

Using Custom Fetcher#

If you wish to create a custom fetcher, you can provide a Mapper string (file#identifier). Codegen will take care of importing it and use it as a fetcher.

schema: MY_SCHEMA_PATH
documents: './src/**/*.graphql'
generates:
./generates.ts:
plugins:
- typescript
- typescript-operations
- typescript-react-query
config:
fetcher: './my-file#myFetcher'

Codegen will use myFetcher, and you can just use the hook directly:

import { useMyQuery } from './generated';
export const MyComponent = () => {
const { status, data, error, isFetching } = useMyQuery({});
};

Your myFetcher should be in the following signature:

type MyFetcher<TData, TVariables> = (operation: string, variables?: TVariables): (() => Promise<TData>)

Usage example#

export const fetchData = <TData, TVariables>(query: string, variables?: TVariables): (() => Promise<TData>) => {
return async () => {
const res = await fetch('https://api.url', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
query,
variables,
}),
});
const json = await res.json();
if (json.errors) {
const { message } = json.errors[0] || 'Error..';
throw new Error(message);
}
return json.data;
};
};

Note: The return value is an async function, with no params, that returns a Promise with the actual data.

Edit this page