📡 GraphQL Request Module

Easy Minimal GraphQL client integration with Nuxt.js.

Features

• Most simple and lightweight GraphQL client.
• Promise-based API (works with async / await).
• Typescript support.
• AST support.
• GraphQL Loader support.

📖 Release Notes 📄 Docs

Setup

1npx nuxi@latest module add graphql-request

For Nuxt2, use nuxt-graphql-request v6:

1
2yarn add nuxt-graphql-request@v6 graphql --dev

nuxt.config.js

1module.exports = {
2  modules: ['nuxt-graphql-request'],
3
4  build: {
5    transpile: ['nuxt-graphql-request'],
6  },
7
8  graphql: {
9    /**
10     * An Object of your GraphQL clients
11     */
12    clients: {
13      default: {
14        /**
15         * The client endpoint url
16         */
17        endpoint: 'https://swapi-graphql.netlify.com/.netlify/functions/index',
18        /**
19         * Per-client options overrides
20         * See: https://github.com/prisma-labs/graphql-request#passing-more-options-to-fetch
21         */
22        options: {},
23      },
24      secondClient: {
25        // ...client config
26      },
27      // ...your other clients
28    },
29
30    /**
31     * Options
32     * See: https://github.com/prisma-labs/graphql-request#passing-more-options-to-fetch
33     */
34    options: {
35      method: 'get', // Default to `POST`
36    },
37
38    /**
39     * Optional
40     * default: false (this includes graphql-tag for node_modules folder)
41     */
42    includeNodeModules: true,
43  },
44};

Runtime Config

If you need to supply your endpoints at runtime, rather than build time, you can use the Runtime Config to provide your values:

nuxt.config.js

1module.exports = {
2  publicRuntimeConfig: {
3    graphql: {
4      clients: {
5        default: {
6          endpoint: '<client endpoint>',
7        },
8        secondClient: {
9          endpoint: '<client endpoint>',
10        },
11        // ...more clients
12      },
13    },
14  },
15};

TypeScript

Type definitions should work out-of-the-box. You should already have Typescript set up to extend Nuxt's auto-generated config. If not, you can start here:

1{
2  "extends": "./.nuxt/tsconfig.json"
3}

Usage

Component

useAsyncData

1<script setup>
2import { gql } from 'nuxt-graphql-request/utils';
3
4const { $graphql } = useNuxtApp();
5
6const query = gql`
7  query planets {
8    allPlanets {
9      planets {
10        id
11        name
12      }
13    }
14  }
15`;
16
17const { data: planets } = await useAsyncData('planets', async () => {
18  const data = await $graphql.default.request(query);
19  return data.allPlanets.planets;
20});
21</script>

User-defined functions

1<script setup>
2import { gql } from 'nuxt-graphql-request/utils';
3
4const { $graphql } = useNuxtApp();
5
6const query = gql`
7  query planets {
8    allPlanets {
9      planets {
10        id
11        name
12      }
13    }
14  }
15`;
16
17const planets = ref([])
18
19const fetchPlanets = () => {
20  const data = await $graphql.default.request(query);
21  planets.value = data.allPlanets.planets;
22}
23</script>

Store actions

1import { defineStore } from 'pinia';
2import { gql } from 'nuxt-graphql-request/utils';
3import { useNuxtApp } from '#imports';
4
5type Planet = { id: number; name: string };
6
7export const useMainStore = defineStore('main', {
8  state: () => ({
9    planets: null as Planet[] | null,
10  }),
11  actions: {
12    async fetchAllPlanets() {
13      const query = gql`
14        query planets {
15          allPlanets {
16            planets {
17              id
18              name
19            }
20          }
21        }
22      `;
23
24      const data = await useNuxtApp().$graphql.default.request(query);
25      this.planets = data.allPlanets.planets;
26    },
27  },
28});

GraphQL Request Client

Examples from the official graphql-request library.

Authentication via HTTP header

1export default defineNuxtConfig({
2  graphql: {
3    clients: {
4      default: {
5        endpoint: 'https://swapi-graphql.netlify.com/.netlify/functions/index',
6        options: {
7          headers: {
8            authorization: 'Bearer MY_TOKEN',
9          },
10        },
11      },
12    },
13  },
14});

Incrementally setting headers

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

1const { $graphql } = useNuxtApp();
2
3// Override all existing headers
4$graphql.default.setHeaders({ authorization: 'Bearer MY_TOKEN' });
5
6// Set a single header
7$graphql.default.setHeader('authorization', 'Bearer MY_TOKEN');

Set endpoint

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

1const { $graphql } = useNuxtApp();
2
3$graphql.default.setEndpoint(newEndpoint);

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<script setup>
2import { gql } from 'nuxt-graphql-request/utils';
3
4const { $graphql } = useNuxtApp();
5
6const requestHeaders = {
7  authorization: 'Bearer MY_TOKEN',
8};
9
10const planets = ref();
11
12const fetchSomething = async () => {
13  const query = gql`
14    query planets {
15      allPlanets {
16        planets {
17          id
18          name
19        }
20      }
21    }
22  `;
23
24  // Overrides the clients headers with the passed values
25  const data = await $graphql.default.request(query, {}, requestHeaders);
26  planets.value = data.allPlanets.planets;
27};
28</script>

Passing more options to fetch

1export default defineNuxtConfig({
2  graphql: {
3    clients: {
4      default: {
5        endpoint: 'https://swapi-graphql.netlify.com/.netlify/functions/index',
6        options: {
7          credentials: 'include',
8          mode: 'cors',
9        },
10      },
11    },
12  },
13});

Or using setHeaders / setHeader:

1const { $graphql } = useNuxtApp();
2
3// Set a single header
4$graphql.default.setHeader('credentials', 'include');
5$graphql.default.setHeader('mode', 'cors');
6
7// Override all existing headers
8$graphql.default.setHeaders({
9  credentials: 'include',
10  mode: 'cors',
11});

Using GraphQL Document variables

1<script setup>
2import { gql } from 'nuxt-graphql-request/utils';
3
4const { $graphql } = useNuxtApp();
5
6const fetchSomething = async () => {
7  const query = gql`
8    query planets($first: Int) {
9      allPlanets(first: $first) {
10        planets {
11          id
12          name
13        }
14      }
15    }
16  `;
17
18  const variables = { first: 10 };
19
20  const planets = await this.$graphql.default.request(query, variables);
21};
22</script>

Error handling

1<script setup>
2import { gql } from 'nuxt-graphql-request/utils';
3
4const { $graphql } = useNuxtApp();
5
6const fetchSomething = async () => {
7  const mutation = gql`
8    mutation AddMovie($title: String!, $releaseDate: Int!) {
9      insert_movies_one(object: { title: $title, releaseDate: $releaseDate }) {
10        title
11        releaseDate
12      }
13    }
14  `;
15
16  const variables = {
17    title: 'Inception',
18    releaseDate: 2010,
19  };
20
21  const data = await $graphql.default.request(mutation, variables);
22};
23</script>

GraphQL Mutations

1<script setup>
2import { gql } from 'nuxt-graphql-request/utils';
3
4const { $graphql } = useNuxtApp();
5
6const fetchSomething = async () => {
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  `;
17
18  try {
19    const data = await $graphql.default.request(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};
26</script>

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 { gql } from 'nuxt-graphql-request/utils';
2
3const { $graphql } = useNuxtApp();
4
5const query = gql`
6  query planets($first: Int) {
7    allPlanets(first: $first) {
8      planets {
9        id
10        name
11      }
12    }
13  }
14`;
15
16const variables = { first: 10 };
17
18const { data, errors, extensions, headers, status } = await $graphql.default.rawRequest(
19  endpoint,
20  query,
21  variables
22);
23console.log(JSON.stringify({ data, errors, extensions, headers, status }, undefined, 2));

Batch queries

1<script setup>
2const { $graphql } = useNuxtApp();
3
4const fetchSomething = async () => {
5  const query1 = /* GraphQL */ `
6    query ($id: ID!) {
7      capsule(id: $id) {
8        id
9        landings
10      }
11    }
12  `;
13
14  const variables1 = {
15    id: 'C105',
16  };
17
18  const query2 = /* GraphQL */ `
19    {
20      rockets(limit: 10) {
21        active
22      }
23    }
24  `;
25
26  const query3 = /* GraphQL */ `
27    query ($id: ID!) {
28      core(id: $id) {
29        id
30        block
31        original_launch
32      }
33    }
34  `;
35
36  const variables3 = {
37    id: 'B1015',
38  };
39
40  try {
41    const data = await $graphql.default.batchRequests([
42      { document: query1, variables: variables1 },
43      { document: query2 },
44      { document: query3, variables: variables3 },
45    ]);
46
47    console.log(JSON.stringify(data, undefined, 2));
48  } catch (error) {
49    console.error(JSON.stringify(error, undefined, 2));
50    process.exit(1);
51  }
52};
53</script>

Cancellation

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

1<script setup>
2import { gql } from 'nuxt-graphql-request/utils';
3
4const { $graphql } = useNuxtApp();
5
6const fetchSomething = async () => {
7  const query = gql`
8    query planets {
9      allPlanets {
10        planets {
11          id
12          name
13        }
14      }
15    }
16  `;
17
18  const abortController = new AbortController();
19
20  const planets = await $graphql.default.request({
21    document: query,
22    signal: abortController.signal,
23  });
24
25  abortController.abort();
26};
27</script>

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

1import 'abort-controller/polyfill';
2
3const abortController = new AbortController();

Middleware

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

Request & response middleware example (set actual auth token to each request & log request trace id if error caused):

1function requestMiddleware(request: RequestInit) {
2  const token = getToken();
3  return {
4    ...request,
5    headers: { ...request.headers, 'x-auth-token': token },
6  };
7}
8
9function responseMiddleware(response: Response<unknown>) {
10  if (response.errors) {
11    const traceId = response.headers.get('x-b3-traceid') || 'unknown';
12    console.error(
13      `[${traceId}] Request error:
14        status ${response.status}
15        details: ${response.errors}`
16    );
17  }
18}
19
20export default defineNuxtConfig({
21  modules: ['nuxt-graphql-request'],
22
23  graphql: {
24    /**
25     * An Object of your GraphQL clients
26     */
27    clients: {
28      default: {
29        /**
30         * The client endpoint url
31         */
32        endpoint: 'https://swapi-graphql.netlify.com/.netlify/functions/index',
33        /**
34         * Per-client options overrides
35         * See: https://github.com/prisma-labs/graphql-request#passing-more-options-to-fetch
36         */
37        options: {
38          requestMiddleware: requestMiddleware,
39          responseMiddleware: responseMiddleware,
40        },
41      },
42
43      // ...your other clients
44    },
45
46    /**
47     * Options
48     * See: https://github.com/prisma-labs/graphql-request#passing-more-options-to-fetch
49     */
50    options: {
51      method: 'get', // Default to `POST`
52    },
53
54    /**
55     * Optional
56     * default: false (this includes graphql-tag for node_modules folder)
57     */
58    includeNodeModules: true,
59  },
60});

FAQ

Why use nuxt-graphql-request over @nuxtjs/apollo?

Don't get me wrong, Apollo Client is great and well maintained by the vue / nuxt community, I used Apollo Client for 18months before switching to graphql-request.

However, as I am obsessed with performances, Apollo Client doesn't work for me at all:

• I don't need another state management as the Vue ecosystem is enough (Vuex & Persisted data).
• I don't need an extra ~120kb parsed in my app for fetching my data.
• I don't need subscriptions as I use pusher.com, there are also alternatives for a WS client: http://github.com/lunchboxer/graphql-subscriptions-client

Why do I have to install graphql?

graphql-request uses a TypeScript type from the graphql package such that if you are using TypeScript to build your project and you are using graphql-request but don't have graphql installed TypeScript build will fail. Details here. If you are a JS user then you do not technically need to install graphql. However, if you use an IDE that picks up TS types even for JS (like VSCode) then it's still in your interest to install graphql so that you can benefit from enhanced type safety during development.

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.

Does nuxt-graphql-request support mutations?

Sure, you can perform any GraphQL queries & mutations as before 👍

Development

1. Clone this repository
2. Install dependencies using yarn install or npm install
3. Start development server using yarn dev or npm run dev

Roadmap

• Support WebSocket client?
• Generate Typed Graphql-request client

📑 License

MIT License