gqlr
Minimaler Fork of the Minimal GraphQL client graphql-request.
Features
- Even simpler than graphql-request! Needlessly duplicated code removed.
- Same Promise-based API (works with
async
/await
). - No Typescript.
- Actually Isomorphic (works with Node / browsers). Ships a real ESM module, instead of the fake one TS generates.
Why?
graphql-request was causing problems downstream due to the fake ESM module it ships, making it incompatible with both browser esm and node.js esm. Additionally, many people are using graphql-request already, so making some simple breaking changes would cause a headache for everyone involved.
Install
npm add gqlr
Quickstart
Send a GraphQL query with a single line of code. ▶️ Try it out.
const query = `{ Movie(title: "Inception") { releaseDate actors { name } }}`
or directly in the browser with native ESM:
const query = `{ Movie(title: "Inception") { releaseDate actors { name } }}`
Usage
// Run GraphQL queries/mutations using a static function // ... or create a GraphQL client instance to send requestsconst client = endpoint headers: {} client
API
import { GraphQLClient, request, rawRequest } from 'gqlr'
Import the GraphQLClient
class, request
and rawRequest
from gqlr
.
client = new GraphQLClient(url, [opts])
Create a new client
instance of GraphQLClient
for a given url
with the following default opts
passed the node-fetch
internally:
method: 'POST' headers: 'Content-Type': 'application/json'
Any opts.headers
are mixed in with the default headers, and any other properties on opts
are passed as fetch
options.
{ headers, status, ...result } = await client.rawRequest(query, [variables])
Make a query
request with a client
including the optional variables
object, returning extra response properties like extensions
.
data = await client.request(query, [variables])
Make a query
request with a client
including the optional variables
object, returning just the data
field.
data = await client.stringRequest(body)
Make a request with a body
string to the configured GQL endpoint. The body should be in the form of:
const body = JSON
Useful with tools like SWR, where you usually stringify a query and variables object into a cache key that gets passed to your fetcher function. With stringRequest
, you can avoid double JSON.stringify
problems, or complex variable scope passing.
client = client.setHeaders(headers)
Pass a headers
object to a client to customize the headers.
client = client.setHeader(key, value)
Set a specific header by a key and a value.
{ headers, status, ...result } = rawRequest(url, query, [variables], [opts])
Convenience function to instantiate a client and make a request in a single function call, returning the extended properties of the graphql request.
data = request(url, query, [variables], [opts])
Convenience function to instantiate a client and make a request in a single function call.
data = stringRequest(url, body, [opts])
Convenience function to instantiate a client and make a stringRequest
in a single function call.
Examples
Authentication via HTTP header
{ const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr' const graphQLClient = endpoint headers: authorization: 'Bearer MY_TOKEN' const query = /* GraphQL */ ` { Movie(title: "Inception") { releaseDate actors { name } } } ` const data = await graphQLClient console}
Passing more options to fetch
{ const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr' const graphQLClient = endpoint credentials: 'include' mode: 'cors' const query = /* GraphQL */ ` { Movie(title: "Inception") { releaseDate actors { name } } } ` const data = await graphQLClient console}
Using variables
{ const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr' const query = /* GraphQL */ ` query getMovie($title: String!) { Movie(title: $title) { releaseDate actors { name } } } ` const variables = title: 'Inception' const data = await console}
Error handling
{ const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr' const query = /* GraphQL */ ` { Movie(title: "Inception") { releaseDate actors { fullname # "Cannot query field 'fullname' on type 'Actor'. Did you mean 'name'?" } } } ` try const data = await console catch error console process }
require
instead of import
Using const request = { const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr' const query = /* GraphQL */ ` { Movie(title: "Inception") { releaseDate actors { name } } } ` const data = await console}
node
Cookie support for npm install fetch-cookie
// This probably only works in CJS environments. require GraphQLClient = { const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr' const graphQLClient = endpoint headers: authorization: 'Bearer MY_TOKEN' const query = /* GraphQL */ ` { Movie(title: "Inception") { releaseDate actors { name } } } ` const data = await graphQLClient console}
Receiving a raw response
The request
method will return the data
or errors
key from the response.
If you need to access the extensions
key you can use the rawRequest
method:
{ const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr' const query = /* GraphQL */ ` { Movie(title: "Inception") { releaseDate actors { name } } } ` const data errors extensions headers status = await console}
FAQ
gqlr
and graphql-request
?
What's the difference between gqlr
is a minimal, mostly drop-in replacement of graphql-request
aimed at:
- shipping artifacts with working esm exports.
- work in the browser without a bundler (even more minimal)
- work with Node.js "type": "module".
- further reducing library size (remove unnecessarily duplicated code)
- removing the project overhead of Typescript syntax, Typescript tooling, and Typescript bugs.
- Clarify undocumented methods and edge-cases.
Breaking changes include:
- No fake 'default' export. If you use this, switch to importing named exports.
- Imports node-fetch. This might break react native, not sure.
This is too simple, to use the power of graphql you must use...
- This module pairs really well with swr and other similar ideas. If you need caching, react hooks and any other party tricks, just use that. Orthogonal concerns ftw.