graphql-request

Minimal GraphQL client supporting Node and browsers for scripts or simple a...

GraphQL
jasonkuhrt/graphql-requestgraphql-request

README

graphql-request


Minimal GraphQL client supporting Node and browsers for scripts or simple apps

GitHub Action npm version


- graphql-request
  - Features
  - Install
  - Quickstart
  - Usage
  - Node Version Support
  - Community
    - GraphQL Code Generator's GraphQL-Request TypeScript Plugin
  - Examples
    - Authentication via HTTP header
      - Incrementally setting headers
      - Set endpoint
      - passing-headers-in-each-request
      - Passing dynamic headers to the client
    - [Passing more options to fetch](#passing-more-options-to-fetch)
    - Custom JSON serializer
    - Using GraphQL Document variables
    - Making a GET request
    - GraphQL Mutations
    - Error handling
    - [Using require instead of import](#using-require-instead-of-import)
    - [Cookie support for node](#cookie-support-for-node)
    - [Using a custom fetch method](#using-a-custom-fetch-method)
    - Receiving a raw response
    - File Upload
      - Browser
      - Node
    - Batching
    - Cancellation
    - Middleware
    - ErrorPolicy
      - None (default)
      - Ignore
      - All
  - FAQ
    - [Why do I have to install graphql?](#why-do-i-have-to-install-graphql)
    - [Do I need to wrap my GraphQL documents inside the gql template exported by graphql-request?](#do-i-need-to-wrap-my-graphql-documents-inside-the-gql-template-exported-by-graphql-request)
    - [What's the difference between graphql-request, Apollo and Relay?](#whats-the-difference-between-graphql-request-apollo-and-relay)


Features


- Most simple & lightweight GraphQL client
- Promise-based API (works with async / await)
- TypeScript support
- Isomorphic (works with Node / browsers)

Install


  1. ```sh
  2. npm add graphql-request graphql
  3. ```

Quickstart


Send a GraphQL query with a single line of code. ▶️ Try it out.

  1. ```js
  2. import { request, gql } from 'graphql-request'

  4. const query = gql`
  5.   {
  6.     company {
  7.       ceo
  8.     }
  9.     roadster {
  10.       apoapsis_au
  11.     }
  12.   }
  13. `

  15. request('https://api.spacex.land/graphql/', query).then((data) => console.log(data))
  16. ```

Usage


  1. ```js
  2. import { request, GraphQLClient } from 'graphql-request'

  4. // Run GraphQL queries/mutations using a static function
  5. request(endpoint, query, variables).then((data) => console.log(data))

  7. // ... or create a GraphQL client instance to send requests
  8. const client = new GraphQLClient(endpoint, { headers: {} })
  9. client.request(query, variables).then((data) => console.log(data))
  10. ```

You can also use the single argument function variant:

  1. ```js
  2. request({
  3.   url: endpoint,
  4.   document: query,
  5.   variables: variables,
  6.   requestHeaders: headers,
  7. }).then((data) => console.log(data))
  8. ```

Node Version Support


We only officially support LTS Node versions. We also make an effort to support two additional versions:

1. The latest even Node version if it is not LTS already.
2. The odd Node version directly following the latest even version.

You are free to try using other versions of Node (e.g. 13.x) with graphql-request but at your own risk.

Community


Get typed GraphQL Queries with GraphQL Code Generator


graphql-request@^5 supports TypedDocumentNode, the typed counterpart of graphql's DocumentNode.

Installing and configuring GraphQL Code Generator requires a few steps in order to get end-to-end typed GraphQL operations using the providedgraphql() helper:

  1. ```ts
  2. import request from 'graphql-request'
  3. import { graphql } from './gql/gql'

  5. const getMovieQueryDocument = graphql(/* GraphQL */ `
  6.   query getMovie($title: String!) {
  7.     Movie(title: $title) {
  8.       releaseDate
  9.       actors {
  10.         name
  11.       }
  12.     }
  13.   }
  14. `)

  16. const data = await request(
  17.   'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr',
  18.   getMovieQueryDocument,
  19.   // variables are type-checked!
  20.   { title: 'Inception' }
  21. )

  23. // `data.Movie` is typed!
  24. ```

_The complete example is available in the GraphQL Code Generator repository_

Visit GraphQL Code Generator's dedicated guide to get started: https://www.the-guild.dev/graphql/codegen/docs/guides/react-vue.

Examples


Authentication via HTTP header


  1. ```js
  2. import { GraphQLClient, gql } from 'graphql-request'

  4. async function main() {
  5.   const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'

  7.   const graphQLClient = new GraphQLClient(endpoint, {
  8.     headers: {
  9.       authorization: 'Bearer MY_TOKEN',
  10.     },
  11.   })

  13.   const query = gql`
  14.     {
  15.       Movie(title: "Inception") {
  16.         releaseDate
  17.         actors {
  18.           name
  19.         }
  20.       }
  21.     }
  22.   `

  24.   const data = await graphQLClient.request(query)
  25.   console.log(JSON.stringify(data, undefined, 2))
  26. }

  28. main().catch((error) => console.error(error))
  29. ```

TypeScript Source

Incrementally setting headers


If you want to set headers after the GraphQLClient has been initialised, you can use the setHeader() or setHeaders() functions.

  1. ```js
  2. import { GraphQLClient } from 'graphql-request'

  4. const client = new GraphQLClient(endpoint)

  6. // Set a single header
  7. client.setHeader('authorization', 'Bearer MY_TOKEN')

  9. // Override all existing headers
  10. client.setHeaders({
  11.   authorization: 'Bearer MY_TOKEN',
  12.   anotherheader: 'header_value',
  13. })
  14. ```

Set endpoint


If you want to change the endpoint after the GraphQLClient has been initialised, you can use the setEndpoint() function.

  1. ```js
  2. import { GraphQLClient } from 'graphql-request'

  4. const client = new GraphQLClient(endpoint)

  6. client.setEndpoint(newEndpoint)
  7. ```

passing-headers-in-each-request


It is possible to pass custom headers for each request. request() and rawRequest() accept a header object as the third parameter

  1. ```js
  2. import { GraphQLClient } from 'graphql-request'

  4. const client = new GraphQLClient(endpoint)

  6. const query = gql`
  7.   query getMovie($title: String!) {
  8.     Movie(title: $title) {
  9.       releaseDate
  10.       actors {
  11.         name
  12.       }
  13.     }
  14.   }
  15. `

  17. const variables = {
  18.   title: 'Inception',
  19. }

  21. const requestHeaders = {
  22.   authorization: 'Bearer MY_TOKEN',
  23. }

  25. // Overrides the clients headers with the passed values
  26. const data = await client.request(query, variables, requestHeaders)
  27. ```

Passing dynamic headers to the client


It's possible to recalculate the global client headers dynamically before each request.
To do that, pass a function that returns the headers to the headers property when creating a new GraphQLClient.

  1. ```js
  2. import { GraphQLClient } from 'graphql-request'

  4. const client = new GraphQLClient(endpoint, {
  5.   headers: () => ({ 'X-Sent-At-Time': Date.now() }),
  6. })

  8. const query = gql`
  9.   query getCars {
  10.     cars {
  11.       name
  12.     }
  13.   }
  14. `
  15. // Function saved in the client runs and calculates fresh headers before each request
  16. const data = await client.request(query)
  17. ```

Passing more options to fetch


  1. ```js
  2. import { GraphQLClient, gql } from 'graphql-request'

  4. async function main() {
  5.   const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'

  7.   const graphQLClient = new GraphQLClient(endpoint, {
  8.     credentials: 'include',
  9.     mode: 'cors',
  10.   })

  12.   const query = gql`
  13.     {
  14.       Movie(title: "Inception") {
  15.         releaseDate
  16.         actors {
  17.           name
  18.         }
  19.       }
  20.     }
  21.   `

  23.   const data = await graphQLClient.request(query)
  24.   console.log(JSON.stringify(data, undefined, 2))
  25. }

  27. main().catch((error) => console.error(error))
  28. ```

TypeScript Source

Custom JSON serializer


If you want to use non-standard JSON types, you can use your own JSON serializer to replace JSON.parse/JSON.stringify used by the GraphQLClient.

An original use case for this feature is BigInt support:

  1. ```js
  2. import JSONbig from 'json-bigint'
  3. import { GraphQLClient, gql } from 'graphql-request'

  5. async function main() {
  6.   const jsonSerializer = JSONbig({ useNativeBigInt: true })
  7.   const graphQLClient = new GraphQLClient(endpoint, { jsonSerializer })
  8.   const data = await graphQLClient.request(
  9.     gql`
  10.       {
  11.         someBigInt
  12.       }
  13.     `
  14.   )
  15.   console.log(typeof data.someBigInt) // if >MAX_SAFE_INTEGER then 'bigint' else 'number'
  16. }
  17. ```

Using GraphQL Document variables


  1. ```js
  2. import { request, gql } from 'graphql-request'

  4. async function main() {
  5.   const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'

  7.   const query = gql`
  8.     query getMovie($title: String!) {
  9.       Movie(title: $title) {
  10.         releaseDate
  11.         actors {
  12.           name
  13.         }
  14.       }
  15.     }
  16.   `

  18.   const variables = {
  19.     title: 'Inception',
  20.   }

  22.   const data = await request(endpoint, query, variables)
  23.   console.log(JSON.stringify(data, undefined, 2))
  24. }

  26. main().catch((error) => console.error(error))
  27. ```

Making a GET request


Queries can be sent as an HTTP GET request:

  1. ```js
  2. import { GraphQLClient, gql } from 'graphql-request'

  4. async function main() {
  5.   const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'

  7.   const graphQLClient = new GraphQLClient(endpoint, {
  8.     method: 'GET',
  9.     jsonSerializer: {
  10.       parse: JSON.parse,
  11.       stringify: JSON.stringify,
  12.     },
  13.   })

  15.   const query = gql`
  16.     query getMovie($title: String!) {
  17.       Movie(title: $title) {
  18.         releaseDate
  19.         actors {
  20.           name
  21.         }
  22.       }
  23.     }
  24.   `

  26.   const variables = {
  27.     title: 'Inception',
  28.   }

  30.   const data = await graphQLClient.request(query, variables)
  31.   console.log(JSON.stringify(data, undefined, 2))
  32. }

  34. main().catch((error) => console.error(error))
  35. ```

GraphQL Mutations


  1. ```js
  2. import { GraphQLClient, gql } from 'graphql-request'

  4. async function main() {
  5.   const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'

  7.   const graphQLClient = new GraphQLClient(endpoint, {
  8.     headers: {
  9.       authorization: 'Bearer MY_TOKEN',
  10.     },
  11.   })

  13.   const mutation = gql`
  14.     mutation AddMovie($title: String!, $releaseDate: Int!) {
  15.       insert_movies_one(object: { title: $title, releaseDate: $releaseDate }) {
  16.         title
  17.         releaseDate
  18.       }
  19.     }
  20.   `

  22.   const variables = {
  23.     title: 'Inception',
  24.     releaseDate: 2010,
  25.   }
  26.   const data = await graphQLClient.request(mutation, variables)

  28.   console.log(JSON.stringify(data, undefined, 2))
  29. }

  31. main().catch((error) => console.error(error))
  32. ```

TypeScript Source

Error handling


  1. ```js
  2. import { request, gql } from 'graphql-request'

  4. async function main() {
  5.   const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'

  7.   const query = gql`
  8.     {
  9.       Movie(title: "Inception") {
  10.         releaseDate
  11.         actors {
  12.           fullname # "Cannot query field 'fullname' on type 'Actor'. Did you mean 'name'?"
  13.         }
  14.       }
  15.     }
  16.   `

  18.   try {
  19.     const data = await request(endpoint, query)
  20.     console.log(JSON.stringify(data, undefined, 2))
  21.   } catch (error) {
  22.     console.error(JSON.stringify(error, undefined, 2))
  23.     process.exit(1)
  24.   }
  25. }

  27. main().catch((error) => console.error(error))
  28. ```

TypeScript Source

Using require instead of import


  1. ```js
  2. const { request, gql } = require('graphql-request')

  4. async function main() {
  5.   const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'

  7.   const query = gql`
  8.     {
  9.       Movie(title: "Inception") {
  10.         releaseDate
  11.         actors {
  12.           name
  13.         }
  14.       }
  15.     }
  16.   `

  18.   const data = await request(endpoint, query)
  19.   console.log(JSON.stringify(data, undefined, 2))
  20. }

  22. main().catch((error) => console.error(error))
  23. ```

Cookie support for node


  1. ```sh
  2. npm install fetch-cookie
  3. ```

  1. ```js
  2. require('fetch-cookie/node-fetch')(require('node-fetch'))

  4. import { GraphQLClient, gql } from 'graphql-request'

  6. async function main() {
  7.   const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'

  9.   const graphQLClient = new GraphQLClient(endpoint, {
  10.     headers: {
  11.       authorization: 'Bearer MY_TOKEN',
  12.     },
  13.   })

  15.   const query = gql`
  16.     {
  17.       Movie(title: "Inception") {
  18.         releaseDate
  19.         actors {
  20.           name
  21.         }
  22.       }
  23.     }
  24.   `

  26.   const data = await graphQLClient.rawRequest(query)
  27.   console.log(JSON.stringify(data, undefined, 2))
  28. }

  30. main().catch((error) => console.error(error))
  31. ```

TypeScript Source

Using a custom fetch method


  1. ```sh
  2. npm install fetch-cookie
  3. ```

  1. ```js
  2. import { GraphQLClient, gql } from 'graphql-request'
  3. import crossFetch from 'cross-fetch'

  5. async function main() {
  6.   const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'

  8.   // a cookie jar scoped to the client object
  9.   const fetch = require('fetch-cookie')(crossFetch)
  10.   const graphQLClient = new GraphQLClient(endpoint, { fetch })

  12.   const query = gql`
  13.     {
  14.       Movie(title: "Inception") {
  15.         releaseDate
  16.         actors {
  17.           name
  18.         }
  19.       }
  20.     }
  21.   `

  23.   const data = await graphQLClient.rawRequest(query)
  24.   console.log(JSON.stringify(data, undefined, 2))
  25. }

  27. main().catch((error) => console.error(error))
  28. ```

Receiving a raw response


The request method will return the data or errors key from the response.
If you need to access the extensions key you can use the rawRequest method:

  1. ```js
  2. import { rawRequest, gql } from 'graphql-request'

  4. async function main() {
  5.   const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'

  7.   const query = gql`
  8.     {
  9.       Movie(title: "Inception") {
  10.         releaseDate
  11.         actors {
  12.           name
  13.         }
  14.       }
  15.     }
  16.   `

  18.   const { data, errors, extensions, headers, status } = await rawRequest(endpoint, query)
  19.   console.log(JSON.stringify({ data, errors, extensions, headers, status }, undefined, 2))
  20. }

  22. main().catch((error) => console.error(error))
  23. ```

File Upload


Browser


  1. ```js
  2. import { request } from 'graphql-request'

  4. const UploadUserAvatar = gql`
  5.   mutation uploadUserAvatar($userId: Int!, $file: Upload!) {
  6.     updateUser(id: $userId, input: { avatar: $file })
  7.   }
  8. `

  10. request('/api/graphql', UploadUserAvatar, {
  11.   userId: 1,
  12.   file: document.querySelector('input#avatar').files[0],
  13. })
  14. ```

Node


  1. ```js
  2. import { createReadStream } from 'fs'
  3. import { request } from 'graphql-request'

  5. const UploadUserAvatar = gql`
  6.   mutation uploadUserAvatar($userId: Int!, $file: Upload!) {
  7.     updateUser(id: $userId, input: { avatar: $file })
  8.   }
  9. `

  11. request('/api/graphql', UploadUserAvatar, {
  12.   userId: 1,
  13.   file: createReadStream('./avatar.img'),
  14. })
  15. ```

TypeScript Source

Batching


It is possible with graphql-request to use batching via thebatchRequests() function. Example available at examples/batching-requests.ts

  1. ```ts
  2. import { batchRequests } from 'graphql-request'
  3. ;(async function () {
  4.   const endpoint = 'https://api.spacex.land/graphql/'

  6.   const query1 = /* GraphQL */ `
  7.     query ($id: ID!) {
  8.       capsule(id: $id) {
  9.         id
  10.         landings
  11.       }
  12.     }
  13.   `

  15.   const query2 = /* GraphQL */ `
  16.     {
  17.       rockets(limit: 10) {
  18.         active
  19.       }
  20.     }
  21.   `

  23.   const data = await batchRequests(endpoint, [
  24.     { document: query1, variables: { id: 'C105' } },
  25.     { document: query2 },
  26.   ])
  27.   console.log(JSON.stringify(data, undefined, 2))
  28. })().catch((error) => console.error(error))
  29. ```

Cancellation


It is possible to cancel a request using an AbortController signal.

You can define the signal in the GraphQLClient constructor:

  1. ```ts
  2. const abortController = new AbortController()

  4. const client = new GraphQLClient(endpoint, { signal: abortController.signal })
  5. client.request(query)

  7. abortController.abort()
  8. ```

You can also set the signal per request (this will override an existing GraphQLClient signal):

  1. ```ts
  2. const abortController = new AbortController()

  4. const client = new GraphQLClient(endpoint)
  5. client.request({ document: query, signal: abortController.signal })

  7. abortController.abort()
  8. ```

In Node environment, AbortController is supported since version v14.17.0.
For Node.js v12 you can use abort-controller polyfill.

  1. ```
  2. import 'abort-controller/polyfill'

  4. const abortController = new AbortController()
  5. ```

Middleware


It's possible to use a middleware to pre-process any request or handle raw response.

Request middleware example (set actual auth token to each request):

  1. ```ts
  2. function middleware(request: RequestInit) {
  3.   const token = getToken()
  4.   return {
  5.     ...request,
  6.     headers: { ...request.headers, 'x-auth-token': token },
  7.   }
  8. }

  10. const client = new GraphQLClient(endpoint, { requestMiddleware: middleware })
  11. ```

It's also possible to use an async function as a request middleware. The resolved data will be passed to the request:

  1. ```ts
  2. async function middleware(request: RequestInit) {
  3.   const token = await getToken()
  4.   return {
  5.     ...request,
  6.     headers: { ...request.headers, 'x-auth-token': token },
  7.   }
  8. }

  10. const client = new GraphQLClient(endpoint, { requestMiddleware: middleware })
  11. ```

Response middleware example (log request trace id if error caused):

  1. ```ts
  2. function middleware(response: Response<unknown>) {
  3.   if (response.errors) {
  4.     const traceId = response.headers.get('x-b3-traceid') || 'unknown'
  5.     console.error(
  6.       `[${traceId}] Request error:
  7.         status ${response.status}
  8.         details: ${response.errors}`
  9.     )
  10.   }
  11. }

  13. const client = new GraphQLClient(endpoint, { responseMiddleware: middleware })
  14. ```

ErrorPolicy


By default GraphQLClient will throw when an error is received. However, sometimes you still want to resolve the (partial) data you received.
You can define errorPolicy in the GraphQLClient constructor.

  1. ```ts
  2. const client = new GraphQLClient(endpoint, { errorPolicy: 'all' })
  3. ```

None (default)


Allow no errors at all. If you receive a GraphQL error the client will throw.

Ignore


Ignore incoming errors and resolve like no errors occurred

All


Return both the errors and data, only works with rawRequest.

FAQ


Why do I have to install graphql?


graphql-request uses methods exposed by the graphql package to handle some internal logic. On top of that, for TypeScript users, some types are used from the graphql package to provide better typings.

Do I need to wrap my GraphQL documents inside the gql template exported by graphql-request?


No. It is there for convenience so that you can get the tooling support like prettier formatting and IDE syntax highlighting. You can use gql from graphql-tag if you need it for some reason too.

What's the difference between graphql-request, Apollo and Relay?


graphql-request is the most minimal and simplest to use GraphQL client. It's perfect for small scripts or simple apps.

Compared to GraphQL clients like Apollo or Relay, graphql-request doesn't have a built-in cache and has no integrations for frontend frameworks. The goal is to keep the package and API as minimal as possible.