Nuxt GraphQL Request

Nuxt GraphQL Request is an open-source Nuxt.js module that integrates the minimal graphql-request client into Nuxt 2 and Nuxt 3, giving apps a promise-based API for GraphQL queries and mutations without Apollo's cache or bundle size.

What is Nuxt GraphQL Request?

Nuxt GraphQL Request is a Nuxt module maintained by Gomah that wraps the graphql-request library from Prisma Labs. It takes a graphql configuration in nuxt.config (client endpoints, options, headers) and injects a $graphql instance into the app for making requests. It supports multiple named clients, runtime configuration, TypeScript, and works with Nuxt 2 (via version 6 of the module) and Nuxt 3.

Key Features

• Minimal GraphQL client — Built on graphql-request, which has no built-in cache and no frontend-framework integrations, keeping the API small.
• Multiple named clients — Configure a default client plus additional clients in nuxt.config under graphql.clients, each with its own endpoint and per-client options.
• Runtime config support — Supply endpoints at runtime via Nuxt's publicRuntimeConfig instead of at build time.
• TypeScript support — Type definitions work out of the box when extending ./.nuxt/tsconfig.json; the graphql package is required for TypeScript builds.
• Middleware — requestMiddleware and responseMiddleware options allow pre-processing requests and handling raw responses, such as injecting auth tokens or logging trace IDs.
• Batch queries and cancellation — batchRequests sends multiple GraphQL documents in one call, and requests can be aborted with an AbortController signal.
• Flexible headers and endpoints — setHeader, setHeaders, and setEndpoint modify the client after initialization; per-request headers can be passed as the third argument to request or rawRequest.

Who is it for?

Nuxt developers who want GraphQL fetching without the overhead of Apollo Client. It is suited for teams that prefer Vuex or Pinia for state management, need multiple GraphQL backends from one app, or want a small dependency for simple apps and scripts. TypeScript users benefit from typed GraphQL requests, and performance-conscious developers avoid Apollo's roughly 120kb parsed bundle (as stated in the maintainer's FAQ).

What can you do with Nuxt GraphQL Request?

• Fetch data in components — Use useAsyncData with $graphql.default.request(query) to load planets or any query result in Nuxt 3 script setup.
• Run mutations — Call GraphQL mutations with request(mutation, variables) and handle errors with try/catch.
• Handle authenticated requests — Set bearer tokens in client options, per-request headers, or dynamically via requestMiddleware.
• Receive raw responses — Use rawRequest() to access data, errors, extensions, headers, and status for advanced use cases.

How does Nuxt GraphQL Request work?

1. Install the module with npx nuxi@latest module add graphql-request.
2. Configure clients in nuxt.config under graphql.clients, specifying endpoints and options.
3. Access the injected $graphql object via useNuxtApp() in components, store actions, or anywhere the Nuxt context is available, then call request, rawRequest, or batchRequests.

FAQ

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

The maintainer chose graphql-request over Apollo Client because Apollo adds roughly 120kb parsed to the app, includes state management that may be redundant with Vuex, and supports subscriptions that can be handled by other services. If you need a cache or subscriptions, Apollo may be the better fit.

Do I need to install the graphql package?

Yes for TypeScript builds — graphql-request uses a TypeScript type from the graphql package, and the build fails without it. JavaScript users can skip it, but installing it improves editor type safety.

Does nuxt-graphql-request support mutations?

Yes, it supports any GraphQL query or mutation, with examples for both in the documentation.

Can I change endpoints at runtime?

Yes. You can provide endpoints through Nuxt's publicRuntimeConfig, or call setEndpoint() on a client after it has been initialized.

Does it have a cache?

No. Like graphql-request, it has no built-in cache; the goal is to keep the package and API minimal.

Alternatives

• @nuxtjs/apollo — a full Apollo Client integration for Nuxt with cache, state management, and subscriptions, but a much larger bundle.
• Relay — a GraphQL client with a built-in cache and data requirements, designed for larger applications and more opinionated workflows.