Minimal GraphQL client supporting Node and browsers for scripts or simple apps
- Highlights
- Install
- Quick Start
- Examples
- Node Version Support
- Reference
- Knowledge Base
- Why was the file upload feature taken away? Will it return?
- Why do I have to install
graphql
? - Do I need to wrap my GraphQL documents inside the
gql
template exported bygraphql-request
? - What sets
graphql-request
apart from other clients like Apollo, Relay, etc.? - Why is the package
main
field missing? - How do I work around React Native + Metro's lack of
exports
support?
- Most simple & lightweight GraphQL client
- Promise-based API (works with
async
/await
) - ESM native package (CJS build is included for now as well, but will eventually be removed)
- First class TypeScript support
- Including
TypedDocumentNode
- Including
- Isomorphic (works in both Nodejs and Browsers)
npm add graphql-request graphql
Send a GraphQL document using a static request function:
import { request, gql } from 'graphql-request'
const document = gql`
{
company {
ceo
}
}
`
await request('https://api.spacex.land/graphql/', document)
The function can be passed a configuration object for more complex cases:
await request({
url,
document,
variables,
requestHeaders,
})
A class is available for constructing your own instances:
import { GraphQLClient } from 'graphql-request'
const document = gql`
{
company {
ceo
}
}
`
const client = new GraphQLClient(endpoint)
await request('https://api.spacex.land/graphql/', document)
- Request:
- GraphQL:
- Configuration:
- Community
- TypeScript
- Other:
We only (officially) support versions of Nodejs of the following status:
- Current
- LTS
- Maintenance and end of life not yet reached
So for example on May 1 2023 that would mean these versions: 16, 18, 19.
Any issue that exists solely for an unsupported version of Nodejs will be rejected (not worked on).
By default GraphQLClient will throw when an error is received. However, sometimes you still want to resolve the (partial) data you received.
You can define errorPolicy
in the GraphQLClient
constructor.
const client = new GraphQLClient(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 with rawRequest
.
In this 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 the graphql
package to handle some internal logic. On top of that, for TypeScript users, some types are used from the graphql
package to provide better typings.
No. It is there for convenience so that you can get the tooling support like prettier formatting and IDE syntax highlighting. You can use gql
from graphql-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.
The main
field was deprecated by Node.js on April 23 2019 when version 12 was released, in favour of entrypoints (exports
package manifest field). I believe enough time has passed that tools should be adopting the new standards now.
You might encounter the error below when you try to build a React Native app that uses graphql-request
:
Error: While trying to resolve module "graphql-request" from file "/path/to/src/App.ts", the package "/path/to/node_modules/graphql-request/package.json" was successfully found. However, this package itself specifies a "main" module field that could not be resolved ("/path/to/node_modules/graphql-request/index".
This happens because Metro does not support yet the exports
field in package.json. A workaround for this problem is to edit the metro.config.js
file in your project and add a new resolveRequest
for graphql-request
. Like this:
resolver: {
resolveRequest: (context, moduleName, platform) => {
if (moduleName.startsWith('graphql-request')) {
return {
filePath: `${__dirname}/node_modules/graphql-request/build/esm/index.js`,
type: 'sourceFile',
}
}
return context.resolveRequest(context, moduleName, platform)
}
}
After doing this change, clear Metro's cache and restart your application.