[Plugin Request] Add typescript-react-query plugin

[balazsorban44]

Is your feature request related to a problem? Please describe.
This would ease the use of React Query with GraphQL in TypeScript codebases.

Describe the solution you'd like
Similar to how hooks are generated for Apollo, I propose to add a plugin for react-query.

Describe alternatives you've considered
Currently there are no alternatives. You can use the types generated by typescript and typescript-operations plugins, but they will only take you so far.

Additional context
https://github.com/tannerlinsley suggested it would be a good idea as well.
https://twitter.com/tannerlinsley/status/1253735766213066752

Some things to consider:

• by default, react-query is not "aware" of that it will be used with GraphQL, as it is agnostic to the data fetching part. So this should be configurable somehow. In the docs, they recommend graphql-request, which would be a nice default. Although I am considering to add a simple fetch wrapper method described here
  This would mean no additional packages are needed, dropping a significant amount of kilobytes from the bundle.

I am currently putting things together for the latter option with these:
Generate types
#4790
Generate named export strings from graphql files
https://github.com/nhi/graphql-operations-string-loader

Open for suggestions.

[michael-land]

if someone needs a starting point, I made a simple plugin for my use case.

The graphql function copied from TanStack/query#301 (comment)

custom plugin

// react-query-codegen.js
const { concatAST, Kind, visit } = require('graphql');
const {
  ClientSideBaseVisitor,
  indentMultiline,
} = require('@graphql-codegen/visitor-plugin-common');

module.exports = {
  plugin: (schema, documents, config) => {
    const allAst = concatAST(documents.map((v) => v.document));

    const allFragments = [
      ...allAst.definitions
        .filter((d) => d.kind === Kind.FRAGMENT_DEFINITION)
        .map((fragmentDef) => ({
          node: fragmentDef,
          name: fragmentDef.name.value,
          onType: fragmentDef.typeCondition.name.value,
          isExternal: false,
        })),
      ...(config.externalFragments || []),
    ];

    const visitor = new TypeScriptDocumentNodesVisitor(schema, allFragments, config, documents);
    const visitorResult = visit(allAst, { leave: visitor });

    return {
      prepend: visitor.getImports(),
      content: [
        visitor.fragments,
        ...visitorResult.definitions.filter((t) => typeof t === 'string'),
        visitor.queries,
      ].join('\n'),
    };
  },
};

class TypeScriptDocumentNodesVisitor extends ClientSideBaseVisitor {
  constructor(schema, fragments, config, documents) {
    super(schema, fragments, config, {}, documents);
  }
  operations = [];

  buildOperation(
    node,
    documentVariableName,
    operationType,
    operationResultType,
    operationVariablesTypes
  ) {
    this.operations.push({
      node,
      documentVariableName,
      operationType,
      operationResultType,
      operationVariablesTypes,
    });
    return null;
  }

  get queries() {
    return `
    import { QueryConfig, useQuery } from 'react-query';

    function graphql<Result, Variables>(query: string, variables?: Variables) {
      return async (): Promise<Result> => {
        const res = await fetch(process.env.GRAPHQL_API, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            authorization: \`Bearer \${localStorage.getItem('token')\}\`,
          },
          credentials: 'include',
          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;
      }
    }
    ${this.operations
      .map(({ node, operationResultType, documentVariableName, operationVariablesTypes }) => {
        const optionalVariables =
          !node.variableDefinitions ||
          node.variableDefinitions.length === 0 ||
          node.variableDefinitions.every(
            (v) => v.type.kind !== Kind.NON_NULL_TYPE || v.defaultValue
          );
        const variables = `variables${optionalVariables ? '?' : ''}: ${operationVariablesTypes}`;

        return `
        export const use${operationResultType} = (${variables}, options?:QueryConfig<${operationResultType}>) => 
        useQuery<${operationResultType}, ${operationVariablesTypes}>(
          ['${node.name.value}', variables],
          graphql<${operationResultType}, ${operationVariablesTypes}>(${documentVariableName}, variables),
          options
        )`;
      })
      .map((s) => indentMultiline(s, 2))
      .join(',\n')}`;
  }
}

Config

// config.yml
overwrite: true
strict: true
config:
  avoidOptionals:
    field: true
  scalars:
    _text: string[]
    bigint: number
    date: string
    float8: number
    inet: string
    numeric: number
    timestamptz: string
    uuid: string

  namingConvention:
    typeNames: change-case#pascalCase
    transformUnderscore: true
hooks:
  afterAllFileWrite:
    - prettier --write
schema: graphql.introspect.json
generates:
  src/api.ts:
    config:
      onlyOperationTypes: true
      enumsAsConst: true
      addDocBlocks: false
      preResolveTypes: true
      skipTypename: true
      documentMode: 'string'
    documents:
      - src/**/*.gql
    plugins:
      - typescript
      - typescript-operations
      - react-query-codegen

How to use it

// index.ts
import React from 'react';
import ReactDOM from 'react-dom';
import { useGetBanksQuery } from './api';

export function App() {
  const query1 = useGetBanksQuery({ limit: 3 });
  const query1Clone = useGetBanksQuery({ limit: 3 });
  const query2 = useGetBanksQuery({ limit: 2 });

  // expected only two requests since query1 and query1Clone have same cache key
  return (
    <>
      <div>{JSON.stringify(query1.data?.banks)}</div>
      <div>{JSON.stringify(query1Clone.data?.banks)}</div>
      <div>{JSON.stringify(query2.data?.banks)}</div>
    </>
  );
}

ReactDOM.render(<App />, document.getElementById('root'));

[dotansimha]

Thanks @balazsorban44 !
I'm moving it to Discussions, since we maintain all plugins requests there.
@xiaoyu-tamu, the plugin you wrote looks really nice, do you want to create a PR for it? :)

[dotansimha]

I was thinking a bit more about that, and here are my thoughts:

• We can generate a react-query hook per each GraphQL operation (like we are doing with other React related libraries).
• It seems like the best way to integrate react-query with GraphQL is graphql-request, so we'll go with this one.
• We need a way to handle the endpoint and headers. It can either be declared statically on codegen config, or it should be able to be provided thought the execution of the hook? What about GraphQLClient from graphql-request?
• I assume no one really wants to provide endpoint and headers everytime, that's why GraphQLClient is useful, but then it means the hook will have to ask for it on each usage? Because we don't have a general React Provider to hold that when used with react-query.

[balazsorban44]

Agree on using a global config for endpoint and headers. I did not go with graphql-request, just to spare some KBs, created my own version. It may not be perfect, but it has worked fine so far:

export default function GQLClient(
  url: RequestInfo,
  options?: RequestInit,
  onError?: ErrorHandler
) {
  const _options: RequestInit = {
    ...options,
    headers: {
      ...options?.headers,
      "Content-Type": "application/json",
    },
    method: "POST",
  }

  async function request<
    TData,
    TVariables extends Record<string, unknown> | undefined = undefined
  >(query: string, variables?: TVariables) {
    const options = {
      ..._options,
      body: JSON.stringify({ query, variables }),
    }

    const res = await fetch(url, options)

    const json = await res.json()
    if (json.errors) {
      const error: GQLErrors = {
        errors: json.errors,
        message: "GQLClientError",
        request: { query, variables },
      }

      if (onError) {
        onError(error)
      } else {
        throw error
      }
    }

    return json.data as TData | undefined
  }
  return {
    options: Object.freeze(_options),
    request,
  }
}

export type GQLClientParams = Parameters<typeof GQLClient>
export type GQLClientType = ReturnType<typeof GQLClient>

export interface GQLRequest {
  query: string
  variables?: Record<string, unknown>
}

type ErrorLocation = {
  line: number
  column: number
}

type GQLError = {
  locations: ErrorLocation[]
  message: string
  path: string[]
}

export type GQLErrors = {
  errors: GQLError[]
  message: string
  request: {
    query: string
    variables?: Record<string, any>
  }
}

export type ErrorHandler = (error: GQLErrors) => void

This is a base. I use react-query in Next.js, so to be able to utilize it in both client and server-side, I have two ways of getting a client instance:

Client side:

/**
 * Get GraphQL Client in browser environments (frontend).
 * If the user has an active session, it will add an accessToken to all requests
 */
export function useClient(options?: RequestInit) {
  const [session] = useSession() // using `next-auth`
  const handleError = useErrorHandler() // using `react-error-boundary`
  const token = session?.accessToken
  return React.useMemo(() => {
    return GQLClient(
      process.env.NEXT_PUBLIC_CONTENT_API,
      token
        ? {
            ...options,
            headers: {
              Authorization: `Bearer ${token}`,
              ...options?.headers,
            },
          }
        : undefined,
      function onError(error) {
        handleError(new AggregateError(error.errors))
      }
    )
  }, [handleError, options, token])
}

Server side:

/**
 * Get GraphQL Client in Node.js environments (server/backend).
 *
 * Always returns a new client instance.
 */
export default async function getClient(options?: GQLClientParams["1"]) {
  const token = await getBuildToken() // getting an access_token from our OAuth2.0 IdP with client credentials
  return GQLClient(
    process.env.NEXT_PUBLIC_CONTENT_API,
    {
      ...options,
      headers: {
        ...(token ? { Authorization: `Bearer ${token}` } : {}),
        ...options?.headers,
      },
    },
    function onError(error) {
      log.error({ ...error, frontend: false }, error.message)
    }
  )
}

[balazsorban44]

@dotansimha One of the biggest gains using my own GraphQLClient instead of graphql-request is that I don't need to add graphql as a peer dependency!

Some info:

https://github.com/prisma-labs/graphql-request/blob/master/package.json#L51

https://twitter.com/balazsorban44/status/1309185248048054274

#4790

Upon reading the docs at https://github.com/dotansimha/graphql-code-generator/blob/f0bd9b8a42da52956292d017f6a3ad450995f1bd/website/docs/plugins/typescript-react-query.md#usage-examples, I understand that your are aiming to support custom fetching, that is awesome! 🎉

[dotansimha]

WIP here: #5107

[dotansimha]

An alpha version is available from this pr (@graphql-codegen/[email protected]) and docs: https://github.com/dotansimha/graphql-code-generator/blob/f0bd9b8a42da52956292d017f6a3ad450995f1bd/website/docs/plugins/typescript-react-query.md#usage-examples

Feedback is welcome :)

@balazsorban44 @xiaoliu-heng

[balazsorban44]

Very nice work, I have to give it a try when I'll have the time, but it looks very promising!

[dotansimha]

Merged and published, you can now use it! @graphql-codegen/[email protected] :)

[michael-land]

It works like a charm.

any ideas how to customize query fn ? e.g. useQuery, usePaginatedQuery, useInfinityQuery

[dotansimha]

In other similar plugins (like the one for react-apollo), we are generating all possible queries. We can add it here as well, maybe with a config flag? will it help?

[michael-land]

Awesome!

I was thinking to add a comment above query to indicate that.

But your solution is easier to implement and less-error-prone.

[Trancever]

@dotansimha Are different types of queries supported e.g. useInfinityQuery? I can't find any information in the documentation and I can see it was mentioned here in the conversation.

[sushilbansal]

Hi @xiaoyu-tamu , do you have any sample code which is working. I tried to use as below but got some errors:

me.tsx

import { gql } from 'graphql-request';

import { UserFragments } from '../../fragments';

export const meQuery = gql`
  query Me {
    me {
      ...UserFragments_user
    }
  }
  ${UserFragments.user}
`;

my codegen.yml

overwrite: true
schema: 'http://localhost:4000/graphql'
documents: 'controller/**/*.tsx'
generates:
  controller/schema.tsx:
    plugins:
      - 'typescript'
      - 'typescript-operations'
      - 'typescript-react-query'
    config:
      fetcher: graphql-request