---
title: "Types"
description: "useSafeRuntimeConfig() is typed from your schema instead of your defaults. See where the types come from and when to regenerate them."
canonical_url: "https://nuxt-safe-runtime-config.onmax.me/guide/type-safety"
---
# Types

> useSafeRuntimeConfig() is typed from your schema instead of your defaults. See where the types come from and when to regenerate them.

`useRuntimeConfig()` infers its types from the defaults in `nuxt.config.ts`, which is wrong in three common cases:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', // typed string, even when production never sets it
    sampleRate: 0, // typed number, but on Nitro 3 NUXT_SAMPLE_RATE=0.5 arrives as '0.5'
    // sentryDsn has no default, so it doesn't exist in the types at all
  },
})
```

`useSafeRuntimeConfig()` takes its types from the schema instead. You don't pass a generic, in components, plugins, `server/api` or `server/utils`:

```ts
const config = useSafeRuntimeConfig()
config.public.apiBase // string
config.port // number | undefined, from optional(number())
config.missingKey // type error
```

## Where the types come from

During `nuxt prepare` and `nuxt dev`, the module writes `.nuxt/types/safe-runtime-config.d.ts` and adds it to the app and server TypeScript projects. For the schema on the [Installation](https://nuxt-safe-runtime-config.onmax.me/guide/installation) page it contains:

```ts [.nuxt/types/safe-runtime-config.d.ts]
export type SafeRuntimeConfig = {
  databaseUrl: string
  public: {
    apiBase: string
    replayEnabled: boolean
  }
}
```

How it builds that type depends on the schema source:

<table>
<thead>
  <tr>
    <th>
      Schema source
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Inline <code>
        $schema
      </code>
    </td>
    
    <td>
      Converted to JSON Schema, then to TypeScript
    </td>
  </tr>
  
  <tr>
    <td>
      A schema module, <code>
        $schema: './file'
      </code>
    </td>
    
    <td>
      The schema's output type
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        envSchema
      </code>
    </td>
    
    <td>
      Each entry's <code>
        @type
      </code>
      
      , whether it's required, and whether it's public
    </td>
  </tr>
</tbody>
</table>

The server runs a schema module's transforms when it starts, so `NUXT_ALLOWED_ORIGINS=a.com,b.com` reaches your code as the array the schema produces. With the deprecated `validateAtRuntime: false`, the transforms never run and the type is the schema's input type.

After you change the schema, run `nuxi prepare` or restart `nuxt dev`. Don't edit the generated file.

## When the types lie

The types describe a config that passed validation. Two cases break that:

- With `onError: 'warn'` or `'ignore'`, a failed check still returns the raw config, untransformed, under the output type. Keep the default `'throw'` wherever you rely on the types.
- In the browser, Nuxt only ships `public`. Private keys are in the type and `undefined` at runtime, so read them in `server/`:

```ts [server/utils/mailer.ts]
export function createMailer() {
  const { smtp } = useSafeRuntimeConfig()
  return createTransport(smtp)
}
```

On Nuxt 4, `useRuntimeConfig()` keeps the types Nuxt gives it, and the [ESLint rule](https://nuxt-safe-runtime-config.onmax.me/guide/eslint) finds the calls to move. On Nuxt 5, the module hands a schema file to Nuxt, which types `useRuntimeConfig()` from it unless the schema has transforms. See [Nuxt 5](https://nuxt-safe-runtime-config.onmax.me/guide/nuxt-5).


## Sitemap

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