Skip to main content
This is the main module to interact with Nhost’s GraphQL service. Typically you would use this module via the main Nhost client but you can also use it directly if you have a specific use case.

Import

import { createClient } from '@nhost/nhost-js/graphql'

Usage

The request method provides type-safe GraphQL operations with full TypeScript support. You can leverage generics to type your responses and use GraphQL document nodes for better integration with third-party libraries.

Basic Usage

import { createClient } from '@nhost/nhost-js'

const nhost = createClient({
  subdomain,
  region
})

const resp = await nhost.graphql.request({
  query: `query GetMovies {
          movies {
            id
            title
            director
            genre
          }
        }`
})

Using Variables

You can pass variables to your GraphQL queries and mutations using the variables option:
import { createClient } from '@nhost/nhost-js'

const nhost = createClient({
  subdomain,
  region
})

const resp = await nhost.graphql.request({
  query: `query GetMovies($genre: String!) {
          movies(where: {genre: {_eq: $genre}}) {
            id
            title
            director
            genre
          }
        }`,
  variables: {
    genre: 'Sci-Fi'
  }
})

console.log(resp.body.data?.movies)
// [
//   {
//     id: '3d67a6d0-bfb5-444a-9152-aea543ebd171',
//     title: 'The Matrix',
//     director: 'Lana Wachowski, Lilly Wachowski',
//     genre: 'Sci-Fi'
//   },
//   {
//     id: '90f374db-16c1-4db5-ba55-643bf38953d3',
//     title: 'Inception',
//     director: 'Christopher Nolan',
//     genre: 'Sci-Fi'
//   },
// ]
This allows you to dynamically pass values to your queries and mutations, making them more flexible and reusable.

Using String Queries with Type Generics

You can type your GraphQL queries and responses using TypeScript generics:
import { createClient } from '@nhost/nhost-js'

const nhost = createClient({
  subdomain,
  region
})

// This is optional but allows you to type the response
// Tools like Apollo Client or The Guild's GraphQL Code Generator
// can generate these document nodes for you.
interface Movies {
  movies: {
    id: string
    title: string
    director: string
    genre: string
  }[]
}

const resp = await nhost.graphql.request<Movies>({
  query: `query GetMovies {
          movies {
            id
            title
            director
            genre
          }
        }`
})

Using GraphQL Document Nodes

For better integration with third-party libraries like Apollo Client or The Guild’s GraphQL Code Generator, you can use GraphQL document nodes created with gql template literal tags:
import { createClient } from '@nhost/nhost-js'
import gql from 'graphql-tag'

const nhost = createClient({
  subdomain,
  region
})

// This is optional but allows you to type the response
// Tools like Apollo Client or The Guild's GraphQL Code Generator
// can generate these document nodes for you.
interface Movies {
  movies: {
    id: string
    title: string
    director: string
    genre: string
  }[]
}

const getMoviesQuery = gql`
  query GetMovies($genre: String!) {
    movies(where: { genre: { _eq: $genre } }) {
      id
      title
      director
      genre
    }
  }
`

const resp = await nhost.graphql.request<Movies>(getMoviesQuery, {
  genre: 'Sci-Fi'
})
console.log(resp.body.data?.movies)
// [
//   {
//     id: '3d67a6d0-bfb5-444a-9152-aea543ebd171',
//     title: 'The Matrix',
//     director: 'Lana Wachowski, Lilly Wachowski',
//     genre: 'Sci-Fi'
//   },
//   {
//     id: '90f374db-16c1-4db5-ba55-643bf38953d3',
//     title: 'Inception',
//     director: 'Christopher Nolan',
//     genre: 'Sci-Fi'
//   },
// ]
Using document nodes enables:
  • Better IDE support with syntax highlighting and validation
  • Integration with code generation tools
  • Compatibility with Apollo Client and other GraphQL libraries

Error handling

The SDK will throw errors in GraphQL operations that respond with an errors attribute with length > 0. The error will be an instance of FetchError<GraphQLResponse> and will contain the response body with the errors.
import { createClient } from '@nhost/nhost-js'
import { FetchError } from '@nhost/nhost-js/fetch'
import type { GraphQLResponse } from '@nhost/nhost-js/graphql'

const nhost = createClient({
  subdomain,
  region
})

try {
  await nhost.graphql.request({
    query: `
        query GetRestrictedObject {
          restrictedObject {
            restrictedField
          }
        }
      `
  })

  expect(true).toBe(false) // This should not be reached
} catch (error) {
  if (!(error instanceof FetchError)) {
    throw error // Re-throw if it's not a FetchError
  }

  const resp = error as FetchError<GraphQLResponse>
  console.log('Error:', JSON.stringify(resp.body, null, 2))
  // Error: {
  //   "body": {
  //     "errors": [
  //       {
  //         "message": "field 'restrictedObject' not found in type: 'query_root'",
  //         "extensions": {
  //           "path": "$.selectionSet.restrictedObject",
  //           "code": "validation-failed"
  //         }
  //       }
  //     ]
  //   },
  //   "status": 200,
  //   "headers": {}
  // }

  // error handling...
}
This type extends the standard Error type so if you want to just log the error you can do so like this:
import { createClient } from '@nhost/nhost-js'
import { FetchError } from '@nhost/nhost-js/fetch'
import type { GraphQLResponse } from '@nhost/nhost-js/graphql'

const nhost = createClient({
  subdomain,
  region
})

try {
  await nhost.graphql.request({
    query: `
        query GetRestrictedObject {
          restrictedObject {
            restrictedField
          }
        }
      `
  })

  expect(true).toBe(false) // This should not be reached
} catch (error) {
  if (!(error instanceof Error)) {
    throw error // Re-throw if it's not an Error
  }

  console.log('Error:', error.message)
  // Error: field 'restrictedObject' not found in type: 'query_root'
}

Interfaces

Client

GraphQL client interface providing methods for executing queries and mutations

Properties

url

url: string
URL for the GraphQL endpoint.

Methods

request()

Call Signature
request<TResponseData, TVariables>(request: GraphQLRequest<TVariables>, options?: RequestInit): Promise<FetchResponse<GraphQLResponse<TResponseData>>>;
Execute a GraphQL query operation Queries are used to fetch data and should not modify any data on the server.
Type Parameters
Type ParameterDefault type
TResponseDataunknown
TVariablesGraphQLVariables
Parameters
ParameterTypeDescription
requestGraphQLRequest<TVariables>GraphQL request object containing query and optional variables
options?RequestInitAdditional fetch options to apply to the request
Returns
Promise<FetchResponse<GraphQLResponse<TResponseData>>> Promise with the GraphQL response and metadata
Call Signature
request<TResponseData, TVariables>(
   document: TypedDocumentNode<TResponseData, TVariables>,
   variables?: TVariables,
   options?: RequestInit): Promise<FetchResponse<GraphQLResponse<TResponseData>>>;
Execute a GraphQL query operation using a typed document node
Type Parameters
Type ParameterDefault type
TResponseData-
TVariablesGraphQLVariables
Parameters
ParameterTypeDescription
documentTypedDocumentNode<TResponseData, TVariables>TypedDocumentNode containing the query and type information
variables?TVariablesVariables for the GraphQL operation
options?RequestInitAdditional fetch options to apply to the request
Returns
Promise<FetchResponse<GraphQLResponse<TResponseData>>> Promise with the GraphQL response and metadata

GraphQLError

Represents a GraphQL error returned from the server.

Properties

extensions?

optional extensions: object;
Additional error information specific to the GraphQL implementation
NameType
codestring
pathstring

locations?

optional locations: object[];
Source locations in the GraphQL document where the error occurred
NameType
columnnumber
linenumber

message

message: string
Error message

path?

optional path: string[];
Path in the query where the error occurred

GraphQLRequest<TVariables>

GraphQL request object used for queries and mutations.

Type Parameters

Type ParameterDefault type
TVariablesGraphQLVariables

Properties

operationName?

optional operationName: string;
Optional name of the operation to execute

query

query: string
The GraphQL query or mutation string

variables?

optional variables: TVariables;
Optional variables for parameterized queries

GraphQLResponse<TResponseData>

Standard GraphQL response format as defined by the GraphQL specification.

Type Parameters

Type ParameterDefault type
TResponseDataunknown

Properties

data?

optional data: TResponseData;
The data returned from successful execution

errors?

optional errors: GraphQLError[];
Array of errors if execution was unsuccessful or partially successful

Type Aliases

GraphQLVariables

type GraphQLVariables = Record<string, unknown>
Variables object for GraphQL operations. Key-value pairs of variable names and their values.

Functions

createAPIClient()

function createAPIClient(url: string, chainFunctions: ChainFunction[]): Client
Creates a GraphQL API client for interacting with a GraphQL endpoint. This client provides methods for executing queries and mutations against a GraphQL API, with support for middleware functions to handle authentication, error handling, and other cross-cutting concerns.

Parameters

ParameterTypeDefault valueDescription
urlstringundefinedBase URL for the GraphQL endpoint
chainFunctionsChainFunction[][]Array of middleware functions for the fetch chain

Returns

Client GraphQL client with query and mutation methods
I