Easy Minimal GraphQL client integration with Nuxt.js.
- Most simple and lightweight GraphQL client.
- Promise-based API (works with
async/await). - Typescript support.
- AST support.
- GraphQL Loader support.
npx nuxi@latest module add graphql-requestFor Nuxt2, use nuxt-graphql-request v6:
yarn add nuxt-graphql-request@v6 graphql --devnuxt.config.js
module.exports = {
modules: ['nuxt-graphql-request'],
build: {
transpile: ['nuxt-graphql-request'],
},
graphql: {
/**
* An Object of your GraphQL clients
*/
clients: {
default: {
/**
* The client endpoint url
*/
endpoint: 'https://swapi-graphql.netlify.com/.netlify/functions/index',
/**
* Per-client options overrides
* See: https://github.com/prisma-labs/graphql-request#passing-more-options-to-fetch
*/
options: {},
},
secondClient: {
// ...client config
},
// ...your other clients
},
/**
* Options
* See: https://github.com/prisma-labs/graphql-request#passing-more-options-to-fetch
*/
options: {
method: 'get', // Default to `POST`
},
/**
* Optional
* default: true (this includes cross-fetch/polyfill before creating the graphql client)
*/
useFetchPolyfill: true,
/**
* Optional
* default: false (this includes graphql-tag for node_modules folder)
*/
includeNodeModules: true,
},
};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
module.exports = {
publicRuntimeConfig: {
graphql: {
clients: {
default: {
endpoint: '<client endpoint>',
},
secondClient: {
endpoint: '<client endpoint>',
},
// ...more clients
},
},
},
};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:
{
"extends": "./.nuxt/tsconfig.json"
}
<script setup>
import { gql } from 'nuxt-graphql-request/utils';
const { $graphql } = useNuxtApp();
const query = gql`
query planets {
allPlanets {
planets {
id
name
}
}
}
`;
const { data: planets } = await useAsyncData('planets', async () => {
const data = await $graphql.default.request(query);
return data.allPlanets.planets;
});
</script><script setup>
import { gql } from 'nuxt-graphql-request/utils';
const { $graphql } = useNuxtApp();
const query = gql`
query planets {
allPlanets {
planets {
id
name
}
}
}
`;
const planets = ref([])
const fetchPlanets = () => {
const data = await $graphql.default.request(query);
planets.value = data.allPlanets.planets;
}
</script>import { defineStore } from 'pinia';
import { gql } from 'nuxt-graphql-request/utils';
import { useNuxtApp } from '#imports';
type Planet = { id: number; name: string };
export const useMainStore = defineStore('main', {
state: () => ({
planets: null as Planet[] | null,
}),
actions: {
async fetchAllPlanets() {
const query = gql`
query planets {
allPlanets {
planets {
id
name
}
}
}
`;
const data = await useNuxtApp().$graphql.default.request(query);
this.planets = data.allPlanets.planets;
},
},
});Examples from the official graphql-request library.
export default defineNuxtConfig({
graphql: {
clients: {
default: {
endpoint: 'https://swapi-graphql.netlify.com/.netlify/functions/index',
options: {
headers: {
authorization: 'Bearer MY_TOKEN',
},
},
},
},
},
});
If you want to set headers after the GraphQLClient has been initialised, you can use the setHeader() or setHeaders() functions.
const { $graphql } = useNuxtApp();
// Override all existing headers
$graphql.default.setHeaders({ authorization: 'Bearer MY_TOKEN' });
// Set a single header
$graphql.default.setHeader('authorization', 'Bearer MY_TOKEN');If you want to change the endpoint after the GraphQLClient has been initialised, you can use the setEndpoint() function.
const { $graphql } = useNuxtApp();
$graphql.default.setEndpoint(newEndpoint);It is possible to pass custom headers for each request. request() and rawRequest() accept a header object as the third parameter
<script setup>
import { gql } from 'nuxt-graphql-request/utils';
const { $graphql } = useNuxtApp();
const requestHeaders = {
authorization: 'Bearer MY_TOKEN',
};
const planets = ref();
const fetchSomething = async () => {
const query = gql`
query planets {
allPlanets {
planets {
id
name
}
}
}
`;
// Overrides the clients headers with the passed values
const data = await $graphql.default.request(query, {}, requestHeaders);
planets.value = data.allPlanets.planets;
};
</script>export default defineNuxtConfig({
graphql: {
clients: {
default: {
endpoint: 'https://swapi-graphql.netlify.com/.netlify/functions/index',
options: {
credentials: 'include',
mode: 'cors',
},
},
},
},
});
Or using setHeaders / setHeader:
const { $graphql } = useNuxtApp();
// Set a single header
$graphql.default.setHeader('credentials', 'include');
$graphql.default.setHeader('mode', 'cors');
// Override all existing headers
$graphql.default.setHeaders({
credentials: 'include',
mode: 'cors',
});<script setup>
import { gql } from 'nuxt-graphql-request/utils';
const { $graphql } = useNuxtApp();
const fetchSomething = async () => {
const query = gql`
query planets($first: Int) {
allPlanets(first: $first) {
planets {
id
name
}
}
}
`;
const variables = { first: 10 };
const planets = await this.$graphql.default.request(query, variables);
};
</script><script setup>
import { gql } from 'nuxt-graphql-request/utils';
const { $graphql } = useNuxtApp();
const fetchSomething = async () => {
const mutation = gql`
mutation AddMovie($title: String!, $releaseDate: Int!) {
insert_movies_one(object: { title: $title, releaseDate: $releaseDate }) {
title
releaseDate
}
}
`;
const variables = {
title: 'Inception',
releaseDate: 2010,
};
const data = await $graphql.default.request(mutation, variables);
};
</script><script setup>
import { gql } from 'nuxt-graphql-request/utils';
const { $graphql } = useNuxtApp();
const fetchSomething = async () => {
const query = gql`
{
Movie(title: "Inception") {
releaseDate
actors {
fullname # "Cannot query field 'fullname' on type 'Actor'. Did you mean 'name'?"
}
}
}
`;
try {
const data = await $graphql.default.request(query);
console.log(JSON.stringify(data, undefined, 2));
} catch (error) {
console.error(JSON.stringify(error, undefined, 2));
process.exit(1);
}
};
</script>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:
import { gql } from 'nuxt-graphql-request/utils';
const { $graphql } = useNuxtApp();
const query = gql`
query planets($first: Int) {
allPlanets(first: $first) {
planets {
id
name
}
}
}
`;
const variables = { first: 10 };
const { data, errors, extensions, headers, status } = await $graphql.default.rawRequest(
endpoint,
query,
variables
);
console.log(JSON.stringify({ data, errors, extensions, headers, status }, undefined, 2));<script setup>
const { $graphql } = useNuxtApp();
const fetchSomething = async () => {
const query1 = /* GraphQL */ `
query ($id: ID!) {
capsule(id: $id) {
id
landings
}
}
`;
const variables1 = {
id: 'C105',
};
const query2 = /* GraphQL */ `
{
rockets(limit: 10) {
active
}
}
`;
const query3 = /* GraphQL */ `
query ($id: ID!) {
core(id: $id) {
id
block
original_launch
}
}
`;
const variables3 = {
id: 'B1015',
};
try {
const data = await $graphql.default.batchRequests([
{ document: query1, variables: variables1 },
{ document: query2 },
{ document: query3, variables: variables3 },
]);
console.log(JSON.stringify(data, undefined, 2));
} catch (error) {
console.error(JSON.stringify(error, undefined, 2));
process.exit(1);
}
};
</script>It is possible to cancel a request using an AbortController signal.
<script setup>
import { gql } from 'nuxt-graphql-request/utils';
const { $graphql } = useNuxtApp();
const fetchSomething = async () => {
const query = gql`
query planets {
allPlanets {
planets {
id
name
}
}
}
`;
const abortController = new AbortController();
const planets = await $graphql.default.request({
document: query,
signal: abortController.signal,
});
abortController.abort();
};
</script>In Node environment, AbortController is supported since version v14.17.0. For Node.js v12 you can use abort-controller polyfill.
import 'abort-controller/polyfill';
const abortController = new AbortController();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):
function requestMiddleware(request: RequestInit) {
const token = getToken();
return {
...request,
headers: { ...request.headers, 'x-auth-token': token },
};
}
function responseMiddleware(response: Response<unknown>) {
if (response.errors) {
const traceId = response.headers.get('x-b3-traceid') || 'unknown';
console.error(
`[${traceId}] Request error:
status ${response.status}
details: ${response.errors}`
);
}
}
export default defineNuxtConfig({
modules: ['nuxt-graphql-request'],
graphql: {
/**
* An Object of your GraphQL clients
*/
clients: {
default: {
/**
* The client endpoint url
*/
endpoint: 'https://swapi-graphql.netlify.com/.netlify/functions/index',
/**
* Per-client options overrides
* See: https://github.com/prisma-labs/graphql-request#passing-more-options-to-fetch
*/
options: {
requestMiddleware: requestMiddleware,
responseMiddleware: responseMiddleware,
},
},
// ...your other clients
},
/**
* Options
* See: https://github.com/prisma-labs/graphql-request#passing-more-options-to-fetch
*/
options: {
method: 'get', // Default to `POST`
},
/**
* Optional
* default: false (this includes cross-fetch/polyfill before creating the graphql client)
*/
useFetchPolyfill: true,
/**
* Optional
* default: false (this includes graphql-tag for node_modules folder)
*/
includeNodeModules: true,
},
});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
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.
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.
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.
Sure, you can perform any GraphQL queries & mutations as before ๐
- Clone this repository
- Install dependencies using
yarn installornpm install - Start development server using
yarn devornpm run dev
- Support WebSocket client?
- Generate Typed Graphql-request client
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent