Repository files navigation

Minimal GraphQL client supporting Node and browsers for scripts or simple apps

• Highlights
• Install
• Quick Start
• Examples
• Node Version Support
• Reference
  • Configuration
    • ErrorPolicy
      • None (default)
      • Ignore
      • All
  • IgnoreOperationName
• Knowledge Base
  • Why was the file upload feature taken away? Will it return?
  • Why do I have to installgraphql?
  • Do I need to wrap my GraphQL documents inside thegql template exported bygraphql-request?
  • What setsgraphql-request apart from other clients like Apollo, Relay, etc.?

• Mostsimple & lightweight GraphQL client
• Promise-based API (works withasync /await)
• Pure ESM package
• First class TypeScript support
  • IncludingTypedDocumentNode
• Isomorphic (works in both Nodejs and Browsers)

npm add graphql-request graphql

Send a GraphQL document using a static request function:

import{gql,request}from'graphql-request'constdocument=gql`  {    company {      ceo    }  }`awaitrequest('https://api.spacex.land/graphql/',document)

The function can be passed a configuration object for more complex cases:

awaitrequest({  url,  document,  variables,  requestHeaders,})

A class is available for constructing your own instances:

import{gql,GraphQLClient}from'graphql-request'constdocument=gql`  {    company {      ceo    }  }`constendpoint='https://api.spacex.land/graphql/'constclient=newGraphQLClient(endpoint)awaitclient.request(document)

• Request:
  • Authentication via HTTP header
  • Method GET
  • Cancellation
  • Headers Per Request (static)
  • Headers Per Request (dynamic)
  • Handle Raw Response
• GraphQL:
  • Document Variables
  • Mutation
  • Batching Requests
• Configuration:
  • Fetch: Passing Options
  • Fetch: Use custom function (e.g. cookie support)
  • Custom JSON Serializer
  • Incremental: Set Endpoint
  • Incremental: Set Request Headers
• Community
  • GraphQL Code Generator for typed GraphQL Queries
• TypeScript
  • UseTypedDocumentNode
• Other:
  • Middleware
  • Error Handling

We only (officially) supportversions of Nodejs of the following status:

• Current
• LTS
• Maintenanceand end of life not yet reached

So for example on Oct 24 2023 that would mean these versions: 18, 20, 21.

Any issue that exists solely for an unsupported version of Nodejs will be rejected (not worked on).

⚠️ This reference is incomplete. Check out theexamples for more reference material.

By default GraphQLClient will throw when an error is received. However, sometimes you still want to resolve the (partial) data you received.You can defineerrorPolicy in theGraphQLClient constructor.

constclient=newGraphQLClient(endpoint,{errorPolicy:'all'})

Allow no errors at all. If you receive a GraphQL error the client will throw.

Ignore incoming errors and resolve like no errors occurred

Return both the errors and data, only works withrawRequest.

OperationName has been introduced to address issues reported hereSupport operation name,However, on certain occasions this information may not be needed in requests. In such cases, you might consider ignoring operationName to avoid the extraction steps currently performed by a parsing operation when the document is provided in string format.

By default the GraphQLClient tries to extract the operationName from the document.You can defineexcludeOperationName in the constructor of GraphQLClient to avoid the extraction process if it is not needed. This can be useful if you don't use operationName and want to optimise queries by reducing the amount of computation as much as possible, especially if we are in a context where we are using documents in string format to reduce bundle size.

// example where the operation name is not ignoredconstclient=newGraphQLClient(endpoint,{method:'POST',})// example in which the operation name is ignoredconstclient=newGraphQLClient(endpoint,{method:'POST',excludeOperationName:true,})

Inthis issue we decided to make this library more stable and maintainable. In principal the feature is still in scope of this library and will make a return when we find time to do the feature right.

graphql-request uses methods exposed by thegraphql package to handle some internal logic. On top of that, for TypeScript users, some types are used from thegraphql package to provide better typings.

No. It is there for convenience so that you can get the tooling support like automatic formatting and syntax highlighting. You can usegql fromgraphql-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.