{"id":13256,"library":"graphql-request","title":"Minimal GraphQL Client for Node & Browsers","description":"graphql-request is a lightweight, promise-based GraphQL client designed for simple applications and scripts in both Node.js and browser environments. It currently maintains version 7.x as its stable series, with `7.4.0` being the latest as of this entry. Releases appear to be somewhat frequent, driven by bug fixes and minor features, often in quick succession (e.g., 7.3.1 to 7.3.5). Key differentiators include its extreme simplicity, minimal footprint compared to full-fledged clients like Apollo or Relay, first-class TypeScript support (including `TypedDocumentNode`), and its isomorphic nature. It focuses on sending raw GraphQL documents and receiving responses without complex caching or state management layers. This makes it ideal for one-off requests or applications where a full client is overkill. Users must manually install `graphql` as a peer dependency.","status":"active","version":"7.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/graffle-js/graffle","tags":["javascript","graphql","request","fetch","graphql-client","typescript"],"install":[{"cmd":"npm install graphql-request","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-request","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-request","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for GraphQL document parsing and validation utilities.","package":"graphql","optional":false}],"imports":[{"note":"For ESM-only consumers (Node.js `--experimental-modules`, browser bundlers). CommonJS support was re-added in v7.3.0, but ESM is preferred.","wrong":"const { request } = require('graphql-request')","symbol":"request","correct":"import { request } from 'graphql-request'"},{"note":"Instantiate for reusable client instances, e.g., with common headers. For ESM-only consumers.","wrong":"const GraphQLClient = require('graphql-request').GraphQLClient","symbol":"GraphQLClient","correct":"import { GraphQLClient } from 'graphql-request'"},{"note":"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`.","wrong":"import gql from 'graphql-tag'","symbol":"gql","correct":"import { gql } from 'graphql-request'"},{"note":"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.","symbol":"ClientError","correct":"import { ClientError } from 'graphql-request'"}],"quickstart":{"code":"import { gql, request } from 'graphql-request'\n\nconst document = gql`\n  query CompanyInfo {\n    company {\n      ceo\n      name\n      founder\n      employees\n    }\n  }\n`\n\nasync function fetchCompanyData() {\n  try {\n    const data = await request('https://api.spacex.land/graphql/', document)\n    console.log('Company Data:', data.company)\n  } catch (error) {\n    if (error.response) {\n      console.error('GraphQL Errors:', error.response.errors)\n      console.error('HTTP Status:', error.response.status)\n    } else {\n      console.error('Network or other error:', error.message)\n    }\n  }\n}\n\nfetchCompanyData();","lang":"typescript","description":"This quickstart demonstrates sending a basic GraphQL query to a public API using the static `request` function."},"warnings":[{"fix":"Ensure 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.","message":"graphql-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.","severity":"breaking","affected_versions":">=3.0.0 <7.3.0, then partially mitigated in >=7.3.0"},{"fix":"For file uploads, consider using `apollo-upload-client` or another GraphQL client that supports the GraphQL Multipart Request Specification.","message":"File 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Run `npm add graphql` or `yarn add graphql` alongside `graphql-request`.","message":"You must manually install the `graphql` package as a peer dependency. `graphql-request` does not bundle it.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update 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`.","message":"The `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.","severity":"breaking","affected_versions":">=7.0.0 <7.3.5"},{"fix":"Review 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.","message":"The 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.","severity":"breaking","affected_versions":">=8.0.0 (unreleased 'next')"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure 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.","cause":"Incorrect module resolution for ESM package in a CommonJS or older TypeScript environment.","error":"Cannot find package 'graphql-request' imported from ..."},{"fix":"Run `npm install graphql` or `yarn add graphql` in your project.","cause":"The `graphql` package, a required peer dependency, is not installed.","error":"Error: 'graphql' is a peer dependency and needs to be installed."},{"fix":"Upgrade 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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'errors') when checking `error.response.errors` for a 4xx/5xx HTTP error."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}