Generate-graphql-client NPM

README

npm i generate-graphql-client --save-dev

This package is designed to generate TypeScript code from the GraphQL schema.

Starting from the root query and mutation, this tool generates TypeScript code for every type it finds. Moreover, it will generate several useful types for GraphQL query validation and a factory function to create a type-safe GraphQL client. Below is an example usage of the generated client.

import { client } from './client'

client.queries
  .user({
    $args: { id: '1001' },
    id: true,
    name: true,
    avatar: true
  })
  .then((user) => {
    // The type of user is `User | null`.
    console.log(user)
  })

In the above TypeScript code, we send a GraphQL query to the server. Both the argument and return type of the client.queries.user method are typed. The code sends the following GraphQL query to the server.

query {
  user(id: "1001") {
    id
    name
    avatar
  }
}

Table of contents:

Get started

Before we start, please make sure the dependencies have been installed.

npm i generate-graphql-query
npm i generate-graphql-client --save-dev

Then create a script and save it to <root>/scripts/graphql.mjs with the following content.

import { generate } from 'generate-graphql-client'

generate({
  files: [
    {
      endpoint: 'https://www.example.com/graphql',
      output: 'src/graphql/types.ts'
    }
  ]
})

!NOTE In the example above, we generate code from the endpoint. However, for security reasons, some endpoints require authentication to query the schema. In such cases, you can configure authorization headers. If an endpoint doesn’t expose an API for schema queries, you can generate code directly from the GraphQL schema.

Now we can run the script to generate the TypeScript code.

# Make sure we are in the <root> directory
node ./scripts/graphql.mjs

!NOTE You can also use the generate-graphql-client command to generate TypeScript code. To do that, just serialize the parameter we passed to the generate function with JSON format and save it to a file. Then run the following command to generate the code.
npx generate-graphql-client --config path/to/config.json
Please note that the relative paths in the JSON config is relative to the JSON file.

The generated code will be saved to src/graphql/types.ts. It contains all the types we found in the schema and exports a factory function as its default export, which we can use to create a GraphQL client.

In the following code, we will create a GraphQL client based on the generated file. Create a file named <root>/graphql/client.ts with the following content.

// We will use generate-graphql-query to generate the query.
import { generateQuery } from 'generate-graphql-query'

// Import the generated factory function.
import createGraphQLClient from './generated'

/**
 * Example of custom options.
 * You can change this type to whatever you want.
 */
export interface Options {
  cache?: 'cache-only' | 'network-only'
}

/**
 * Define a function to send GraphQL query.
 * In this example we will use the Fetch API.
 * You can use whatever you want, maybe axios for example.
 * You can also add authorization headers here if needed.
 */
const sendQuery = async (query: string, options?: Options) => {
  // Handle the options.
  console.log(options)

  return fetch('https://www.example.com/graphql', {
    method: 'post',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query })
  }).then((res) => res.json())
}

/**
 * Create the GraphQL client with the generated factory function.
 * The factory function accepts a async function as its parameter and
 * the async function accepts the following four parameters:
 *
 * - `type`: The operation type (query or mutation).
 * - `name`: The operations name. If `name` is `null`, means that the
 *    caller is `query()` or `mutation()`. If `name` is a string, means
 *    that the caller is `queries.xxx()` or `mutations.xxx()`.
 * - `payload`: If `name` is `null`, `payload` is the first parameter
 *    of `query()` or `mutation()`. If `name` is a string, `payload`
 *    is the first parameter of `queries.xxx()` or `mutations.xxx()`.
 * - `options`: Custom options. The second parameter of the client
 *    methods.
 */
export const client = createGraphQLClient<Options>(
  async (type, name, payload, options) => {
    // If name is `null`, means that the caller function is `query()` or
    // `mutation()` and `payload` is the first parameter of `query()` or
    // `mutation()`. In this case, we should return the entire response
    // json.
    if (name === null) {
      return sendQuery(generateQuery({ [type]: payload }), options)
    }

    // If `name` is a string, means that the caller function is
    // `queries.xxx()` or `mutations.xxx()` and `payload` is the first
    // parameter of `queries.xxx()` or `mutations.xxx()`. In this case,
    // we should return the expected data and throw error if something
    // went wrong.
    return sendQuery(
      generateQuery({ [type]: { [name]: payload } }),
      options
    ).then((res) => {
      if (res.errors?.[0]) {
        throw new Error(res.errors[0].message)
      }
      return res.data[name]
    })
  }
)

The client has the following properties.

query A function that can be used to send multiple queries.
queries An object containing all query methods the GraphQL API supports.
mutation A function that can be used to send multiple mutations.
mutations An object containing all mutation methods the GraphQL API supports.

!CAUTION If the GraphQL API does not provide any queries, query and queries will not be generated. And if the GraphQL API does not provide any mutations, mutation and mutations will not be generated.

Handle authorization when generating code from endpoints

For security reasons, some endpoints require authentication to query the schema. In such cases, we can add headers through the endpoint config. For example:

import { generate } from 'generate-graphql-client'

generate({
  files: [
    {
      endpoint: {
        url: 'https://www.example.com/graphql',
        headers: {
          Authorization: 'Bearer ***'
        }
      },
      output: 'src/graphql/types.ts'
    }
  ]
})

In the code above, we add authorization headers directly in the script file. While this works as expected, we may not want to commit these headers to our source tree. To prevent this, we can use the headerFile config to reference an external JSON file for the authorization headers and add that file to .gitignore. For example:

import { generate } from 'generate-graphql-client'

generate({
  files: [
    {
      endpoint: {
        url: 'https://www.example.com/graphql',
        headersFile: 'src/graphql/headers.json'
      },
      output: 'src/graphql/types.ts'
    }
  ]
})

The content of src/graphql/headers.json is:

{
  "Authorization": "Bearer ***"
}

In the code above, the content of src/graphql/headers.json will be used as headers for the endpoint. To prevent this file from being committed to the source tree, you should add it to .gitignore.

Generate code directly from the GraphQL schema

If the endpoint does not allow schema queries or if adding headers to the request is inconvenient. We can generate code from the GraphQL schema files.

First we need to convert the GraphQL schema files to a introspection JSON file.

Install the generate-graphql-introspection command:

npm i generate-graphql-introspection --save-dev

Generate the introspection file:

npx generate-graphql-introspection -s src/graphql/schema.graphql -o src/graphql/introspection.json

Generate code from the generated introspection file:

import { generate } from 'generate-graphql-client'

generate({
  files: [
    {
      filename: 'src/graphql/introspection.json',
      output: 'src/graphql/types.ts'
    }
  ]
})

!NOTE If your schema is divided into multiple .graphql files. You can use a glob to specify the schema path. For example:
npx generate-graphql-introspection -s "src/graphql/*.graphql" -o src/graphql/introspection.json
You can run npx generate-graphql-introspection -h for its docs.

Examples

This section provides examples demonstrating how to use the generated GraphQL client.