---
title: "Nuxt 5"
description: "Nuxt 5 checks runtime config types itself. Point the module at a schema file and Nuxt types useRuntimeConfig() from it, while the module runs the checks Nuxt skips."
canonical_url: "https://nuxt-safe-runtime-config.onmax.me/guide/nuxt-5"
---
# Nuxt 5

> Nuxt 5 checks runtime config types itself. Point the module at a schema file and Nuxt types useRuntimeConfig() from it, while the module runs the checks Nuxt skips.

Nuxt 5 accepts a schema in `runtimeConfig`. From it, Nuxt fills defaults, converts `NUXT_*` strings to numbers, booleans, enums and JSON, refuses to start when a required value is missing, and types `useRuntimeConfig()`. Without a schema, it infers the same from your defaults.

Nuxt reduces each schema to a type outline when it loads the config. When the server starts, it doesn't run URL formats, minimums and maximums, patterns, custom refinements or transforms. This module runs them, with your schema as written.

## Point the module at a schema file

Put the schema in its own file and pass its path:

<code-group>

```ts [runtime-config.schema.ts]
import { z } from 'zod'

export default z.object({
  databaseUrl: z.url(),
  port: z.number().int().min(1).default(3000),
  mode: z.enum(['draft', 'send']).default('draft'),
  apiSecret: z.string().refine(value => value.startsWith('sk_'), 'must start with sk_'),
  public: z.object({
    apiBase: z.url().default('https://api.example.com'),
    replayEnabled: z.boolean().default(false),
  }),
})
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['nuxt-safe-runtime-config'],
  safeRuntimeConfig: {
    $schema: './runtime-config.schema',
  },
})
```

</code-group>

The module hands the schema to Nuxt, so you don't need a `runtimeConfig` block. Values you do set in `runtimeConfig` become defaults. `useRuntimeConfig()` comes out typed from the schema:

```ts [server/api/send.post.ts]
import { defineEventHandler, useRuntimeConfig } from 'nuxt/server'

export default defineEventHandler(() => {
  const config = useRuntimeConfig()
  config.port // number
  config.mode // 'draft' | 'send'
})
```

When the server starts, each layer stops it with its own error. Nuxt reports a wrong type or a missing value:

```txt
[NUXT_E8014] The runtime config does not match its schema:
  - `port` (`NUXT_PORT`) must be integer, but received a string.
```

The module reports what your schema rejects:

```txt
[safe-runtime-config] Validation failed!
  1. apiSecret: must start with sk_
```

`useSafeRuntimeConfig()` still works and keeps the exact output type of the schema.

## Schemas Nuxt can't use

Nuxt needs a schema that implements [Standard JSON Schema](https://standardschema.dev/json-schema) and validates synchronously. Zod 4 and ArkType do. Wrap a Valibot schema with `toStandardJsonSchema()` from `@valibot/to-json-schema`.

A schema with transforms or asynchronous checks has no type outline, so the module keeps it to itself and logs why. `useRuntimeConfig()` then keeps the types Nuxt infers from your defaults, and `useSafeRuntimeConfig()` returns the transformed values typed from the schema.

## Preserve validation settings

Nuxt's native schema checks always stop startup on an invalid type or a missing required value. The module therefore hands your schema to Nuxt only when runtime validation is enabled and `onError` is `'throw'` (the defaults).

With `validateAtRuntime: false` or `onError: 'warn' | 'ignore'`, the schema stays with the module, which logs why and respects those settings. `useSafeRuntimeConfig()` keeps its schema type; `useRuntimeConfig()` keeps the types Nuxt infers from your defaults. Set a `runtimeConfig` block for the values Nuxt should expose, as with other module-only schemas. Nuxt still enforces types inferred from those defaults and schemas you declare directly in `runtimeConfig`.

## Keep the schema out of `nuxt.config.ts`

On Nuxt 5, an inline Zod `$schema` makes Nuxt fail while it loads the config, before any module runs. Nuxt copies the config at that point, and the copy breaks Zod's classes. Only schemas inside `runtimeConfig` are taken out before the copy. Use a schema file.

A schema you write straight into `runtimeConfig` belongs to Nuxt alone. Nuxt keeps its type outline and drops the schema itself, so the module can't run its formats or refinements. When both declare the same key, Nuxt uses the one in `nuxt.config.ts`.

## Prerendering

The module checks every value when the prerenderer starts, so a required value that isn't set fails the build with Nuxt's `NUXT_E8015`. Set the variables the schema requires before you prerender.

## `.env.example`

An [`envSchema`](https://nuxt-safe-runtime-config.onmax.me/guide/env-schema) app keeps working on Nuxt 5. Nuxt lets those variables through untyped, and the module checks them against the file when the server starts.

## ViteHub Env

[ViteHub Env](https://vitehub.dev/docs/env) replaces runtime config instead of checking it. It fixes public values at build time and wraps secrets in a `SecretEnv` you have to `.unseal()`. Server code reads `useServerEnv(event)` and app code reads `usePublicEnv()`, the same way in Nuxt, Vite and Nitro apps. It reads the same `.env.example` format, but its code-first declarations drop minimum lengths, patterns, URL formats, transforms and refinements. If that trade fits your app, [migrate to it](https://nuxt-safe-runtime-config.onmax.me/guide/migrate-to-vitehub-env).


## Sitemap

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