---
title: "Introduction"
description: "Fail the build or the server start when runtime config is wrong, and read it through a composable typed from your schema."
canonical_url: "https://nuxt-safe-runtime-config.onmax.me/guide"
---
# Introduction

> Fail the build or the server start when runtime config is wrong, and read it through a composable typed from your schema.

Nuxt 4 never checks runtime config. A server that starts without `NUXT_DATABASE_URL` boots fine, and the first request that needs the database fails. On Nitro 3, `NUXT_PUBLIC_REPLAY_ENABLED=false` reaches your code as the string `'false'`, which is truthy. And `useRuntimeConfig()` takes its types from the defaults in `nuxt.config.ts`, so a secret that defaults to `''` is typed `string` whether anyone set it or not.

Nuxt 5 checks types and required values, but not URL formats, ranges, patterns, refinements or transforms. [Nuxt 5](https://nuxt-safe-runtime-config.onmax.me/guide/nuxt-5) shows how the module adds those on top.

This module puts a schema on runtime config. When a value is missing or has the wrong type, `nuxt build` stops:

```txt
$ nuxt build
[safe-runtime-config] Validation failed!
  1. databaseUrl: Invalid key: Expected "databaseUrl" but received undefined
  2. public.apiBase: Invalid URL: Received "not a url"
```

When the values pass, `useSafeRuntimeConfig()` returns them with the types your schema declares:

```ts [server/api/report.post.ts]
export default defineEventHandler((event) => {
  const config = useSafeRuntimeConfig(event)
  config.databaseUrl // string
  config.public.replayEnabled // boolean, even when the server starts with NUXT_PUBLIC_REPLAY_ENABLED=false
})
```

The schema can be a [Valibot, Zod or ArkType](https://nuxt-safe-runtime-config.onmax.me/guide/installation) object, or an annotated [`.env.example`](https://nuxt-safe-runtime-config.onmax.me/guide/env-schema).

## What it checks

- The values in `nuxt.config.ts` during `nuxt dev` and `nuxt build`, and the values the server starts with after `NUXT_*` overrides. You don't pick one; [Validation](https://nuxt-safe-runtime-config.onmax.me/guide/validation) explains what each check sees.
- `NUXT_*` strings, which it converts to the booleans, numbers, enums and JSON your schema asks for before checking them. See [Environment variables](https://nuxt-safe-runtime-config.onmax.me/guide/environment-overrides).
- Your code, through types generated from the schema for the app and for `server/`. See [Types](https://nuxt-safe-runtime-config.onmax.me/guide/type-safety).

## What it costs

You keep a schema next to `runtimeConfig`, and every new key goes in both. The `.env.example` source avoids that, because the file declares the keys.

The server start check adds a Nitro plugin and a middleware. To keep your schema library out of the server bundle, the module converts an inline schema to JSON Schema at build time. Transforms and custom refinements have no JSON Schema form, so a schema that uses them moves to its own file.

## Requirements

Nuxt 4, or the Nuxt 5 nightly. It runs on Nitro 2 (`nitropack` 2.13 or later) and Nitro 3. The `.env.example` source needs Node.js 22 or later for `nuxt prepare` and `nuxt build`.

<tip>

On Nuxt 5, the module hands a schema file to Nuxt, so `useRuntimeConfig()` is typed from it too. See [Nuxt 5](https://nuxt-safe-runtime-config.onmax.me/guide/nuxt-5).

</tip>

[Install the module](https://nuxt-safe-runtime-config.onmax.me/guide/installation) to add a schema to an existing app.


## Sitemap

See the full [sitemap](https://nuxt-safe-runtime-config.onmax.me/sitemap.md) for all pages.
