graphql-request — Minimal GraphQL Client for Node and Browsers

Introduction

graphql-request is a minimal, dependency-light GraphQL client for JavaScript and TypeScript. It provides a simple function-based API for sending GraphQL queries and mutations over HTTP, making it the go-to choice when you need to talk to a GraphQL API without the overhead of a full-featured client like Apollo or Relay. Its small footprint and straightforward API make it popular for scripts, serverless functions, and applications where a caching layer is unnecessary.

What graphql-request Does

• Sends GraphQL queries, mutations, and subscriptions over HTTP with a single function call
• Returns typed responses when used with TypeScript and GraphQL Code Generator
• Supports custom headers, authentication tokens, and request middleware
• Handles file uploads via the GraphQL multipart request specification
• Provides batched query support for sending multiple operations in a single HTTP request

Architecture Overview

graphql-request is built as a thin wrapper around the Fetch API (or a configurable HTTP client). The core request function accepts an endpoint URL, a GraphQL document (string or tagged template), and optional variables, then constructs and sends an HTTP POST request with the standard GraphQL JSON body format. The GraphQLClient class adds stateful configuration — base URL, default headers, and middleware — for repeated use across an application. Error handling parses GraphQL error responses and throws typed errors with access to both the response data and error details.

Self-Hosting & Configuration

• Install via npm: npm install graphql-request graphql
• Use the standalone request() function for one-off queries with zero setup
• Create a GraphQLClient instance for shared configuration across multiple queries
• Set default headers (like authorization tokens) on the client instance
• Configure request and response middleware for logging, error handling, or token refresh

Key Features

• Minimal API surface: a single function for simple use cases, a client class for advanced configuration
• First-class TypeScript support with generic type parameters for fully typed query responses
• File upload support following the GraphQL multipart request specification
• Batched requests that send multiple GraphQL operations in a single HTTP call
• Works in Node.js, browsers, Deno, Bun, and serverless environments without polyfills

Comparison with Similar Tools

• Apollo Client — a full-featured client with caching, local state, and React integration; graphql-request is for when you just need to send queries without the complexity
• urql — a lightweight but extensible client with exchangeable cache strategies; graphql-request is even simpler with no caching layer at all
• Relay — Meta's GraphQL client with compiler-driven optimization; graphql-request prioritizes simplicity over compile-time optimizations
• fetch + JSON.stringify — manual HTTP calls work but lack error parsing, typed responses, and middleware; graphql-request adds just enough abstraction
• graphql-tag — only parses GraphQL strings into AST documents; graphql-request handles the full request lifecycle

FAQ

Q: When should I use graphql-request instead of Apollo Client? A: Use graphql-request when you need simple query execution without caching, normalized state, or framework-specific integrations. It is ideal for server-side scripts, CLI tools, serverless functions, and lightweight applications.

Q: Does graphql-request support subscriptions? A: The library focuses on HTTP-based queries and mutations. For real-time subscriptions over WebSocket, you would use a dedicated library like graphql-ws alongside graphql-request.

Q: How do I add authentication headers? A: Create a GraphQLClient instance with a headers option: new GraphQLClient(url, { headers: { Authorization: 'Bearer token' } }). Headers can also be set per-request.

Q: Can I use graphql-request with React? A: Yes. While it does not include React hooks like Apollo Client, you can use it inside React components with useEffect, or pair it with TanStack Query (React Query) for caching and refetching.

Sources

• https://github.com/jasonkuhrt/graphql-request
• https://www.npmjs.com/package/graphql-request