graphql-request

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

Features

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

Install

1npm add graphql-request

Quickstart

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

1import { request } from 'graphql-request'
2
3const query = `{
4  Movie(title: "Inception") {
5    releaseDate
6    actors {
7      name
8    }
9  }
10}`
11
12request('https://api.graph.cool/simple/v1/movies', query).then((data) => console.log(data))

Usage

1import { request, GraphQLClient } from 'graphql-request'
2
3// Run GraphQL queries/mutations using a static function
4request(endpoint, query, variables).then((data) => console.log(data))
5
6// ... or create a GraphQL client instance to send requests
7const client = new GraphQLClient(endpoint, { headers: {} })
8client.request(query, variables).then((data) => console.log(data))

Examples

Authentication via HTTP header

1import { GraphQLClient } from 'graphql-request'
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const graphQLClient = new GraphQLClient(endpoint, {
7    headers: {
8      authorization: 'Bearer MY_TOKEN',
9    },
10  })
11
12  const query = /* GraphQL */ `
13    {
14      Movie(title: "Inception") {
15        releaseDate
16        actors {
17          name
18        }
19      }
20    }
21  `
22
23  const data = await graphQLClient.request(query)
24  console.log(JSON.stringify(data, undefined, 2))
25}
26
27main().catch((error) => console.error(error))

TypeScript Source

Passing more options to fetch

1import { GraphQLClient } from 'graphql-request'
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const graphQLClient = new GraphQLClient(endpoint, {
7    credentials: 'include',
8    mode: 'cors',
9  })
10
11  const query = /* GraphQL */ `
12    {
13      Movie(title: "Inception") {
14        releaseDate
15        actors {
16          name
17        }
18      }
19    }
20  `
21
22  const data = await graphQLClient.request(query)
23  console.log(JSON.stringify(data, undefined, 2))
24}
25
26main().catch((error) => console.error(error))

TypeScript Source

Using variables

1import { request } from 'graphql-request'
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const query = /* GraphQL */ `
7    query getMovie($title: String!) {
8      Movie(title: $title) {
9        releaseDate
10        actors {
11          name
12        }
13      }
14    }
15  `
16
17  const variables = {
18    title: 'Inception',
19  }
20
21  const data = await request(endpoint, query, variables)
22  console.log(JSON.stringify(data, undefined, 2))
23}
24
25main().catch((error) => console.error(error))

TypeScript Source

Error handling

1import { request } from 'graphql-request'
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const query = /* GraphQL */ `
7    {
8      Movie(title: "Inception") {
9        releaseDate
10        actors {
11          fullname # "Cannot query field 'fullname' on type 'Actor'. Did you mean 'name'?"
12        }
13      }
14    }
15  `
16
17  try {
18    const data = await request(endpoint, query)
19    console.log(JSON.stringify(data, undefined, 2))
20  } catch (error) {
21    console.error(JSON.stringify(error, undefined, 2))
22    process.exit(1)
23  }
24}
25
26main().catch((error) => console.error(error))

TypeScript Source

Using require instead of import

1const { request } = require('graphql-request')
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const query = /* GraphQL */ `
7    {
8      Movie(title: "Inception") {
9        releaseDate
10        actors {
11          name
12        }
13      }
14    }
15  `
16
17  const data = await request(endpoint, query)
18  console.log(JSON.stringify(data, undefined, 2))
19}
20
21main().catch((error) => console.error(error))

Cookie support for node

1npm install fetch-cookie

1require('fetch-cookie/node-fetch')(require('node-fetch'))
2
3import { GraphQLClient } from 'graphql-request'
4
5async function main() {
6  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
7
8  const graphQLClient = new GraphQLClient(endpoint, {
9    headers: {
10      authorization: 'Bearer MY_TOKEN',
11    },
12  })
13
14  const query = /* GraphQL */ `
15    {
16      Movie(title: "Inception") {
17        releaseDate
18        actors {
19          name
20        }
21      }
22    }
23  `
24
25  const data = await graphQLClient.rawRequest(query)
26  console.log(JSON.stringify(data, undefined, 2))
27}
28
29main().catch((error) => console.error(error))

TypeScript Source

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:

1import { rawRequest } from 'graphql-request'
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const query = /* GraphQL */ `
7    {
8      Movie(title: "Inception") {
9        releaseDate
10        actors {
11          name
12        }
13      }
14    }
15  `
16
17  const { data, errors, extensions, headers, status } = await rawRequest(endpoint, query)
18  console.log(JSON.stringify({ data, errors, extensions, headers, status }, undefined, 2))
19}
20
21main().catch((error) => console.error(error))

TypeScript Source

More examples coming soon...

• Fragments
• Using graphql-tag

FAQ

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.