Clients reference

TypeScript Client

This is the base implementation of the WunderGraph HTTP protocol in TypeScript that can be used on both browser and server environments. It's used as the base interface for the Web client, React and Next.js implementations.

Configuration

Let's start by adding the WunderGraph TypeScript client generator to your project.

1
2
3
4
5
6
7
8
9
10
11
// wundergraph.config.ts
configureWunderGraphApplication({
// ... your configuration
codeGenerators: [
{
templates: [templates.typescript.client],
path: '../generated',
},
],
})

Create the client

The generated createClient will return a fully typesafe client that can be used to execute operations.

1
2
3
import { createClient } from 'generated/client'
const client = createClient()

Client configuration

Custom baseURL

The client can be configured with a custom baseURL.

1
2
3
const client = createClient({
baseURL: 'https://my-custom-base-url.com',
})

Node.js support

You can use the client on server environments that don't have a build-in fetch implementation by using the customFetch configuration option.

Install node-fetch or any other fetch polyfill.

1
npm i node-fetch

And add it to the client configuration.

1
2
3
4
5
import fetch from 'node-fetch'
const client = createClient({
customFetch: fetch,
})

Browser

If you target older browsers you will need a polyfill for fetch, AbortController, AbortSignal and possibly Promise.

1
2
3
4
5
6
7
import 'promise-polyfill/src/polyfill'
import 'yet-another-abortcontroller-polyfill'
import { fetch } from 'whatwg-fetch'
const client = createClient({
customFetch: fetch,
})

Adding custom headers

1
2
3
4
5
6
7
8
9
10
11
const client = createClient({
extraHeaders: {
customHeader: 'value',
},
})
// or
client.setExtraHeaders({
customHeader: 'value',
})

Methods

Run a query

1
2
3
4
5
6
const response = await client.query({
operationName: 'Hello',
input: {
hello: 'World',
},
})

Mutation

1
2
3
4
5
6
const response = await client.mutate({
operationName: 'SetName',
input: {
name: 'WunderGraph',
},
})

LiveQuery

1
2
3
4
5
6
7
8
9
10
client.subscribe(
{
operationName: 'Hello',
input: {
name: 'World',
},
liveQuery: true,
},
(response) => {}
)

Subscription

1
2
3
4
5
6
7
8
9
client.subscribe(
{
operationName: 'Countdown',
input: {
from: 100,
},
},
(response) => {}
)

One-of subscription

You can run subscriptions using subscribeOnce, this will return the subscription response directly and will not setup a stream. This is useful for SSR purposes for example.

1
2
3
4
5
6
7
8
9
10
const response = await client.subscribe(
{
operationName: 'Countdown',
input: {
from: 100,
},
subscribeOnce: true,
},
(response) => {}
)

Upload files

1
2
3
4
const { fileKeys } = await client.uploadFiles({
provider: S3Provider.minio,
files,
})

Auth

Login

1
client.login('github')

Log out

1
2
3
client.logout({
logoutOpenidConnectProvider: true,
})

Fetch user

1
const user = await client.fetchUser()

AbortController

Almost all methods accept an AbortController instance that can be used to cancel the request.

1
2
3
4
5
6
7
8
9
10
const controller = new AbortController()
const { fileKeys } = await client.uploadFiles({
abortSignal: abortController.signal,
provider: S3Provider.minio,
files,
})
// cancel the request
controller.abort()

Error handling

Operations

Query and mutation errors are returned as a GraphQLResponseError object. By default, the first error specifiy the error message but you can access all GraphQL errors through the errors property. Network errors and non 2xx responses are returned as a ResponseError object and contain the status code as statusCode property.

1
2
3
4
5
6
7
8
9
10
11
12
const { data, error } = await client.query({
operationName: 'Hello',
input: {
hello: 'World',
},
})
if (error instanceof GraphQLResponseError) {
error.errors[0].location
} else if (error instanceof ResponseError) {
error.statusCode
}

Other

Methods that initiate a network request throw a ResponseError or Error if the request fails to initiate or the response is not 2xx. You can be sure that the request was successful if the method doesn't throw an error.

Limitations

  • Subscriptions are not supported server side, but can be fetched using subscribeOnce.
Previous
Overview

Was this article helpful to you?
Provide feedback

Edit this page