API - Server Setup - Yoga Configuration

Yoga Configuration

Customize GraphQL Yoga options like GraphiQL, error masking, logging, and landing page.

The yogaConfig option in defineConfig (or createApiServer) lets you override GraphQL Yoga's built-in behavior. It accepts all Yoga options except schema and context, which are managed internally.

Type #

1
2
3
4
5
type YogaConfigOverrides = Omit<
  NonNullable<Parameters<typeof createYoga>[0]>,
  "schema" | "context"
>

Available overrides #

Option	Type	Default	Description
`healthCheckEndpoint`	`string`	`"/live"`	Path for the health check endpoint
`graphiql`	`boolean \| object`	`true` in development	Enable/configure GraphiQL IDE
`logging`	`boolean \| LogLevel`	Based on `API_LOGGER` env	Control Yoga's internal logging
`maskedErrors`	`boolean`	`true`	Hide internal error details from clients
`landingPage`	`boolean`	`false`	Show Yoga's default landing page

Default behavior #

Without any overrides, the server applies these defaults:

GraphiQL is enabled when NODE_ENV=development
maskedErrors is true — internal errors are replaced with generic messages
Logging level is controlled by the API_LOGGER environment variable (default: warn ). Set to silent to disable Yoga logging entirely.
Landing page is disabled

Usage #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import { defineConfig } from "@lakeql/api/config"

import { getUser } from "./auth"
import { allConfigs } from "./config-registry"
import { permissions } from "./permissions"

const baseDir = import.meta.dirname

export const config = defineConfig({
  allConfigs,
  baseDir,
  getUser,
  permissions,
  port: 4000,
  schemaPath: "./schemas",
  yogaConfig: {
    graphiql: {
      title: "LakeQL Explorer",
      defaultQuery: "{ __typename }",
    },
    maskedErrors: false, // expose full errors in development
    healthCheckEndpoint: "/healthz",
  },
})

Logging configuration #

The API_LOGGER environment variable accepts these values:

Value	Effect
`debug`	All messages
`info`	Info, warnings, and errors
`warn`	Warnings and errors (default)
`error`	Errors only
`silent`	No Yoga logging output

1
2
3
# .env
API_LOGGER=debug