---
title: "Installation"
description: "Add the module, write a schema for your runtime config in Valibot, Zod or ArkType, and watch the build reject a bad value."
canonical_url: "https://nuxt-safe-runtime-config.onmax.me/guide/installation"
---
# Installation

> Add the module, write a schema for your runtime config in Valibot, Zod or ArkType, and watch the build reject a bad value.

<code-collapse>

```txt [Prompt]
Add nuxt-safe-runtime-config to my Nuxt app.

- Read https://nuxt-safe-runtime-config.onmax.me/raw/guide/installation.md first
- Run `npx nuxi module add nuxt-safe-runtime-config`
- Write a schema for every key in `runtimeConfig`, with the schema library the app already uses (Valibot, Zod or ArkType), and set it as `safeRuntimeConfig.$schema`
- Leave values that production sets through `NUXT_*` variables as `''` in `runtimeConfig`
- Replace `useRuntimeConfig()` with `useSafeRuntimeConfig()`, passing `event` in server handlers
- Run `nuxi prepare` and the typecheck, and fix each config error instead of casting
```

</code-collapse>

<steps>

### Install the module

```bash
npx nuxi module add nuxt-safe-runtime-config
```

Add a schema library if the app has none. The examples use Valibot, and each block has a Zod and an ArkType tab.

```bash
pnpm add valibot
```

### Describe your runtime config

Write a schema that covers every key in `runtimeConfig`, `public` included, and pass it as `$schema`:

<code-group>

```ts [Valibot]
import * as v from 'valibot'

export default defineNuxtConfig({
  modules: ['nuxt-safe-runtime-config'],
  runtimeConfig: {
    databaseUrl: 'postgresql://localhost:5432/app',
    public: {
      apiBase: 'https://api.example.com',
      replayEnabled: false,
    },
  },
  safeRuntimeConfig: {
    $schema: v.object({
      databaseUrl: v.pipe(v.string(), v.url()),
      public: v.object({
        apiBase: v.pipe(v.string(), v.url()),
        replayEnabled: v.boolean(),
      }),
    }),
  },
})
```

```ts [Zod]
import { z } from 'zod'

export default defineNuxtConfig({
  modules: ['nuxt-safe-runtime-config'],
  runtimeConfig: {
    databaseUrl: 'postgresql://localhost:5432/app',
    public: {
      apiBase: 'https://api.example.com',
      replayEnabled: false,
    },
  },
  safeRuntimeConfig: {
    $schema: z.object({
      databaseUrl: z.string().url(),
      public: z.object({
        apiBase: z.string().url(),
        replayEnabled: z.boolean(),
      }),
    }),
  },
})
```

```ts [ArkType]
import { type } from 'arktype'

export default defineNuxtConfig({
  modules: ['nuxt-safe-runtime-config'],
  runtimeConfig: {
    databaseUrl: 'postgresql://localhost:5432/app',
    public: {
      apiBase: 'https://api.example.com',
      replayEnabled: false,
    },
  },
  safeRuntimeConfig: {
    $schema: type({
      databaseUrl: 'string.url',
      public: {
        apiBase: 'string.url',
        replayEnabled: 'boolean',
      },
    }),
  },
})
```

</code-group>

Any library that implements [Standard Schema](https://standardschema.dev/) works. Valibot 1, Zod 3.24 and later, and ArkType 2 do.

<warning>

On Nuxt 5, an inline Zod schema breaks Nuxt's config loader. Put the schema in [its own file](https://nuxt-safe-runtime-config.onmax.me/guide/nuxt-5) instead.

</warning>

### Read the config

`useSafeRuntimeConfig()` is auto-imported in components, plugins and `server/`:

```vue [app.vue]
<script setup lang="ts">
const config = useSafeRuntimeConfig()
config.public.apiBase // string
</script>
```

In a server handler, pass the event, as you would to `useRuntimeConfig(event)`:

```ts [server/api/health.get.ts]
export default defineEventHandler((event) => {
  const { databaseUrl } = useSafeRuntimeConfig(event)
  return checkDatabase(databaseUrl)
})
```

### Break it on purpose

Set `apiBase` to `'not a url'` and run `nuxt dev`. It stops before serving anything:

```txt
[safe-runtime-config] Validation failed!
  1. public.apiBase: Invalid URL: Received "not a url"
```

Each message comes from your schema library, so Zod and ArkType word it differently.

</steps>

## If production sets `NUXT_*` variables

The check above reads `nuxt.config.ts`. When production sets `NUXT_DATABASE_URL` as the server starts, the build never sees that value. Leave it empty in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    databaseUrl: '',
  },
})
```

The build skips the empty value, and the server checks the value it actually received when it starts. [Validation](https://nuxt-safe-runtime-config.onmax.me/guide/validation) explains both checks and `requireAtBuild`, for CI that builds with every production value.

<tip>

For an explicit import in app code, use `#imports`:

```ts
import { useSafeRuntimeConfig } from '#imports'
```

In server code, use the server alias instead:

```ts [server/utils/config.ts]
import { useSafeRuntimeConfig } from '#safe-runtime-config/server'
```

The server alias reads Nitro's runtime config directly. On Nuxt 5, importing from `#imports` in server code activates Nuxt's Nitro v2 compatibility layer and warns `NUXT_B9003`. Server auto-imports already use the server implementation.

</tip>

Next, run the [ESLint rule](https://nuxt-safe-runtime-config.onmax.me/guide/eslint) to find the `useRuntimeConfig()` calls that are still untyped.


## Sitemap

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