Serverless Functions Overview

Nhost Functions are server-side JavaScript or TypeScript functions that are deployed as HTTP endpoints. They are a great option for handling events (event triggers, cron triggers, and one-off scheduled events), integrating with external services like Stripe or Slack, and building custom API logic.

Tip

For more sophisticated use-cases and control over the runtime, use Nhost Run.

How Functions Work

Each .js or .ts file you place in the ./functions directory of your project becomes an HTTP endpoint. A function exports a default handler that receives an Express Request and Response:

import type { Request, Response } from 'express'

export default (req: Request, res: Response) => {
  res.status(200).send('Hello World!')
}

Routing

Endpoints are generated based on the file path relative to ./functions:

File	HTTP Endpoint
functions/index.js	https://[subdomain].functions.[region].nhost.run/v1/
functions/users/index.ts	https://[subdomain].functions.[region].nhost.run/v1/users
functions/users/active.ts	https://[subdomain].functions.[region].nhost.run/v1/users/active
functions/my-company.js	https://[subdomain].functions.[region].nhost.run/v1/my-company

All HTTP methods (GET, POST, PUT, DELETE, etc.) are routed to the same handler. Use req.method to differentiate.

Directory Conventions

• Files and folders prefixed with an underscore (_) are ignored and not exposed as endpoints. Use this for shared utilities.
• index files map to the parent directory path.

Request and Response

Functions receive standard Express Request and Response objects with a few additions:

Property	Description
req.method	HTTP method (GET, POST, etc.)
req.headers	Request headers
req.query	Parsed query string parameters
req.body	Parsed request body (JSON, form data)
req.rawBody	Raw request body as a Buffer
req.invocationId	Unique identifier for this function invocation

The invocationId is useful for correlating logs across a single invocation.

Environment Variables

The following environment variables are automatically injected into your functions at runtime:

Variable	Description
NHOST_ADMIN_SECRET	Admin secret for your project
NHOST_WEBHOOK_SECRET	Webhook secret for your project
NHOST_JWT_SECRET	JWT secret configuration (JSON string)
NHOST_SUBDOMAIN	Project subdomain
NHOST_REGION	Project region
NHOST_HASURA_URL	Internal GraphQL engine URL
NHOST_AUTH_URL	Internal Auth URL
NHOST_GRAPHQL_URL	Internal GraphQL URL
NHOST_STORAGE_URL	Internal Storage URL
NHOST_FUNCTIONS_URL	Internal Functions URL

Any custom environment variables you define are also available.

Deployment

Functions are deployed automatically when you push to the connected GitHub repository. Nhost computes checksums for your functions and their dependencies, so unchanged functions are skipped during deployment.

Nhost detects your package manager based on the lockfile present in the functions folder or a parent folder. See Runtimes and Dependencies for details.

Billing

Functions are billed per GB-sec or GB-hour. 1 GB-hour is 3600 GB-seconds.

1 GB-sec is 1 function with 1 GB of RAM running for 1 second. If 1 function with 1 GB of RAM runs for 3600 seconds, that equals 1 GB-hour.

Concepts

Local Development

Run and test functions locally with the Nhost CLI

Runtimes

Supported Node.js versions and package managers

Logging

Log format, execution metrics, and request tracing

Metrics

Invocations, response times, and error rates (Pro/Team/Enterprise)

Limitations

Supported languages, timeouts, and payload limits

Guides

Getting Started

Create and deploy your first function

JWT Verification

Verify access tokens with symmetric and asymmetric keys

Custom JWTs

Generate tokens to act on behalf of users

GraphQL Server

Run a GraphQL Yoga server as a function

Error Handling

Handle errors gracefully and debug failures

Using the Nhost SDK

Query GraphQL, upload files, and call Nhost services from functions

CORS

Handle cross-origin requests from browser clients

Event Webhooks

Handle event triggers, cron triggers, and one-off scheduled events