Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
request
✓ import { request } from 'graphql-request'
✗ const { request } = require('graphql-request')
For ESM-only consumers (Node.js `--experimental-modules`, browser bundlers). CommonJS support was re-added in v7.3.0, but ESM is preferred.
GraphQLClient
✓ import { GraphQLClient } from 'graphql-request'
✗ const GraphQLClient = require('graphql-request').GraphQLClient
Instantiate for reusable client instances, e.g., with common headers. For ESM-only consumers.
gql
✓ import { gql } from 'graphql-request'
✗ import gql from 'graphql-tag'
This `gql` utility from `graphql-request` is a no-op passthrough for string literals, primarily for tooling and type inference. It's not strictly necessary at runtime but recommended for clarity and compatibility with `TypedDocumentNode`. It is *not* `graphql-tag`.
ClientError
✓ import { ClientError } from 'graphql-request'
Use this class to catch and inspect errors from the GraphQL server, which includes HTTP status and GraphQL errors. `error.response.errors` will contain GraphQL errors even on non-2xx HTTP responses.
This quickstart demonstrates sending a basic GraphQL query to a public API using the static `request` function.
import { gql, request } from 'graphql-request'
const document = gql`
query CompanyInfo {
company {
ceo
name
founder
employees
}
}
`
async function fetchCompanyData() {
try {
const data = await request('https://api.spacex.land/graphql/', document)
console.log('Company Data:', data.company)
} catch (error) {
if (error.response) {
console.error('GraphQL Errors:', error.response.errors)
console.error('HTTP Status:', error.response.status)
} else {
console.error('Network or other error:', error.message)
}
}
}
fetchCompanyData();
Debug
Known issues
breakinggraphql-request transitioned to a Pure ESM package. This requires specific `tsconfig.json` and `package.json` configurations for TypeScript users, including `"type": "module"` and `"moduleResolution": "bundler"` or `"node16"`/`"nodenext"`. While CommonJS support was re-added in v7.3.0, the package's primary orientation remains ESM.fixEnsure your `package.json` contains `"type": "module"`. For TypeScript, set `"moduleResolution": "bundler"` or `"node16"`/`"nodenext"` in `tsconfig.json`. If using CommonJS, explicit `.js` extensions might be needed for imports, or rely on the v7.3.0 CommonJS re-introduction.
affects: >=3.0.0 <7.3.0, then partially mitigated in >=7.3.0
breakingFile upload functionality was explicitly removed to maintain a lightweight core. If you require file uploads, you will need to use a different client or a separate library for handling multipart forms.fixFor file uploads, consider using `apollo-upload-client` or another GraphQL client that supports the GraphQL Multipart Request Specification.
affects: >=3.0.0
gotchaYou must manually install the `graphql` package as a peer dependency. `graphql-request` does not bundle it.fixRun `npm add graphql` or `yarn add graphql` alongside `graphql-request`.
affects: >=1.0.0
breakingThe `ClientError` structure for non-2xx HTTP responses (e.g., 4xx/5xx) has been significantly refined across versions 7.3.2 to 7.3.5. Earlier versions might not have correctly exposed GraphQL errors from the response body in `error.response.errors` or handled non-JSON error bodies gracefully.fixUpdate to `graphql-request@7.3.5` or later to ensure robust error handling for non-2xx HTTP responses, including correct parsing of GraphQL errors and graceful handling of non-JSON response bodies. Access `error.response.errors` and `error.response.data`.
affects: >=7.0.0 <7.3.5
breakingThe upcoming 'next' release introduces several breaking changes related to SDDM extensions, argument mapping, and removal of deprecated exports. Existing code using these advanced features will require refactoring.fixReview the 'next' branch changelog carefully upon release. Specifically, adapt to new descriptive property names in SDDM extensions, merged `ArgumentsMap` and SDDM, and replace any usage of removed deprecated exports.
affects: >=8.0.0 (unreleased 'next')
Errors
Common errors & fixes
Cannot find package 'graphql-request' imported from ...
Incorrect module resolution for ESM package in a CommonJS or older TypeScript environment.
fixEnsure your `package.json` contains `"type": "module"` and for TypeScript, `"moduleResolution": "bundler"` or `"node16"`/`"nodenext"` in `tsconfig.json`. Alternatively, for Node.js CommonJS, ensure you are on `graphql-request` v7.3.0+ which re-added CJS support.
Error: 'graphql' is a peer dependency and needs to be installed.
The `graphql` package, a required peer dependency, is not installed.
fixRun `npm install graphql` or `yarn add graphql` in your project.
TypeError: Cannot read properties of undefined (reading 'errors') when checking `error.response.errors` for a 4xx/5xx HTTP error.
An older version of `graphql-request` (pre-7.3.5) might not have correctly populated the `errors` array on `ClientError` for non-2xx responses, or the response body was not valid JSON.
fixUpgrade to `graphql-request@7.3.5` or later. Always check for `error.response` and then `error.response.errors` as it might be undefined if the error is not a GraphQL response error.
Audit
Dependencies
graphqlrequiredPeer dependency required for GraphQL document parsing and validation utilities.