Skip to main content
This is the main module to interact with Nhost’s Functions 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

You can import and use this package with: 
import { createClient } from '@nhost/nhost-js/functions'

​
Usage

You can use this library by passing the path to the function you want to call and any body or fetch options you want to apply (optional): 
import { createClient } from '@nhost/nhost-js'

const nhost = createClient({
  subdomain,
  region
})

const funcResp = await nhost.functions.post('/helloworld', {
  message: 'Hello, World!'
})
console.log(JSON.stringify(funcResp.body, null, 2))
// {
//   "message": "Hello, World!"
// }
The post method above is a convenience method for executing a POST request with a JSON body. For more generic requests, you can use the fetch method instead: 
import { createClient } from '@nhost/nhost-js'

const nhost = createClient({
  subdomain,
  region
})

const funcResp = await nhost.functions.fetch('/helloworld', {
  method: 'GET',
  headers: {
    Accept: 'text/plain',
    ContentType: 'application/json'
  }
})
console.log(funcResp.body)
// "Hello, World!"

​
Error handling

The SDK will throw errors in most operations if the request returns a status >=300 or if the request fails entirely (i.e., due to network errors). The type of the error will be a FetchError<T>: 
import { createClient } from '@nhost/nhost-js'
import { FetchError } from '@nhost/nhost-js/fetch'

const nhost = createClient({
  subdomain,
  region
})

try {
  await nhost.functions.fetch('/helloworld', {
    method: 'GET',
    headers: {
      Accept: 'application/octet-stream'
    }
  })
} catch (error) {
  if (!(error instanceof FetchError)) {
    throw error // Re-throw if it's not a FetchError
  }

  console.log('Error:', JSON.stringify(error, null, 2))
  // Error: {
  //   "body": "Unsupported Accept Header",
  //   "status": 400,
  //   "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'

const nhost = createClient({
  subdomain,
  region
})

try {
  await nhost.functions.fetch('/helloworld', {
    method: 'GET',
    headers: {
      Accept: 'application/octet-stream'
    }
  })
} catch (error) {
  if (!(error instanceof Error)) {
    throw error // Re-throw if it's not a FetchError
  }

  console.log('Error:', error.message)
  // Error: Unsupported Accept Header
  // error handling...
}

​
Interfaces

​
Client

Functions client interface providing methods for executing serverless function calls

​
Properties

​
baseURL

baseURL: string

​
Methods

​
fetch()

fetch<T>(path: string, options?: RequestInit): Promise<FetchResponse<T>>;
Execute a request to a serverless function The response body will be automatically parsed based on the content type into the following types:
  • Object if the response is application/json
  • string text string if the response is text/*
  • Blob if the response is any other type
Type Parameters
Type ParameterDefault type
Tunknown
Parameters
ParameterTypeDescription
pathstringThe path to the serverless function
options?RequestInitAdditional fetch options to apply to the request
Returns
Promise<FetchResponse<T>> Promise with the function response and metadata.

​
post()

post<T>(
   path: string,
   body?: unknown,
   options?: RequestInit): Promise<FetchResponse<T>>;
Executes a POST request to a serverless function with a JSON body This is a convenience method assuming the request is a POST with JSON body setting the Content-Type and ‘Accept’ headers to application/json and automatically stringifying the body. For a more generic request, use the fetch method instead.
Type Parameters
Type ParameterDefault type
Tunknown
Parameters
ParameterTypeDescription
pathstringThe path to the serverless function
body?unknownThe JSON body to send in the request
options?RequestInitAdditional fetch options to apply to the request
Returns
Promise<FetchResponse<T>> Promise with the function response and metadata

​
pushChainFunction()

pushChainFunction(chainFunction: ChainFunction): void;
Add a middleware function to the fetch chain
Parameters
ParameterTypeDescription
chainFunctionChainFunctionThe middleware function to add
Returns
void

​
Functions

​
createAPIClient()

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

​
Parameters

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

​
Returns

Client Functions client with fetch method