---
title: "Environment variables"
description: "How NUXT_* strings become the booleans, numbers and JSON your schema expects, and where transforms and refinements go."
canonical_url: "https://nuxt-safe-runtime-config.onmax.me/guide/environment-overrides"
---
# Environment variables

> How NUXT_* strings become the booleans, numbers and JSON your schema expects, and where transforms and refinements go.

Environment variables are strings, and Nitro hands them to runtime config in two different ways. Nitro 3 passes them unchanged, so `NUXT_PUBLIC_REPLAY_ENABLED=false` arrives as `'false'`. Nitro 2 parses some of them, so `NUXT_PORT=3000` arrives as the number `3000` and `NUXT_VERSION=1.10` as `1.1`. A schema that says `boolean()` rejects the first, and one that says `string()` rejects the others.

When the server starts, the module converts these values before it validates them.

## Coercion

The module converts a value only when the schema would reject it as it is:

<table>
<thead>
  <tr>
    <th>
      The schema expects
    </th>
    
    <th>
      The module converts
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        'true'
      </code>
      
      , <code>
        'false'
      </code>
      
      , <code>
        '1'
      </code>
      
       and <code>
        '0'
      </code>
      
       in any case, and the numbers <code>
        1
      </code>
      
       and <code>
        0
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      numeric strings, such as <code>
        '0.5'
      </code>
      
       or <code>
        '3000'
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      integral strings, such as <code>
        '3000'
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      integers and booleans that Nitro 2 parsed, such as <code>
        123
      </code>
      
       or <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      an array or an object
    </td>
    
    <td>
      JSON strings, such as <code>
        '["email","github"]'
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      an enum or a literal
    </td>
    
    <td>
      strings that convert to one of the allowed values
    </td>
  </tr>
</tbody>
</table>

So a plain schema is enough:

```ts [nuxt.config.ts]
import * as v from 'valibot'

export default defineNuxtConfig({
  runtimeConfig: {
    public: { replayEnabled: false, sampleRate: 0.1 },
  },
  safeRuntimeConfig: {
    $schema: v.object({
      public: v.object({
        replayEnabled: v.boolean(),
        sampleRate: v.number(),
      }),
    }),
  },
})
```

Start the server with `NUXT_PUBLIC_REPLAY_ENABLED=true NUXT_PUBLIC_SAMPLE_RATE=0.4` and `useSafeRuntimeConfig().public` is `{ replayEnabled: true, sampleRate: 0.4 }`, on the server and in the client payload.

Don't reach for `z.coerce` or a `v.transform()` to do this yourself. `z.coerce.boolean()` turns `'false'` into `true`.

Coercion never guesses:

- A value the schema already accepts stays as it is. A field typed `union([boolean(), string()])` keeps `'true'` as a string.
- A value it cannot convert still fails. `NUXT_PUBLIC_REPLAY_ENABLED=maybe` is an error, not `false`.
- Nitro 2 has already turned `NUXT_VERSION=1.10` into `1.1` and the original spelling is gone, so a `string` field rejects it instead of returning `'1.1'`.
- In a union of objects, a branch whose literal fields contradict the value, such as `kind: 'a'`, is skipped.

The module writes the converted values back into runtime config, so code that still calls `useRuntimeConfig(event)` sees them too.

## Transform values with a schema module

Coercion fixes types. To split a list, trim a trailing slash or check one field against another, the server has to run your schema library, and an inline `$schema` can't do that. The module converts it to JSON Schema at build time, and some features don't survive:

<table>
<thead>
  <tr>
    <th>
      Library
    </th>
    
    <th>
      Fails the build
    </th>
    
    <th>
      Converts, but the server skips the check
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Valibot
    </td>
    
    <td>
      <code>
        v.transform()
      </code>
      
      , <code>
        v.check()
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      Zod
    </td>
    
    <td>
      <code>
        .transform()
      </code>
    </td>
    
    <td>
      <code>
        .refine()
      </code>
      
      , <code>
        .superRefine()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      ArkType
    </td>
    
    <td>
      
    </td>
    
    <td>
      <code>
        .narrow()
      </code>
      
      , morphs such as <code>
        .pipe()
      </code>
    </td>
  </tr>
</tbody>
</table>

The right column matters most. A `.refine()` passes the build check, because the build runs Zod as written, and then the server never runs it.

Put the schema in its own file and default-export it:

```ts [runtime-config.schema.ts]
import * as v from 'valibot'

export default v.object({
  allowedOrigins: v.pipe(
    v.string(),
    v.transform(value => value.split(',').map(origin => origin.trim())),
  ),
  public: v.object({
    apiBase: v.pipe(v.string(), v.url(), v.transform(url => url.replace(/\/$/, ''))),
  }),
})
```

Then point `$schema` at the file, relative to the project root:

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

The server runs the schema once, after Nitro applies overrides, and `useSafeRuntimeConfig()` returns its output. `allowedOrigins` is a `string[]`, transformed `public` values reach the client payload, and the [generated types](https://nuxt-safe-runtime-config.onmax.me/guide/type-safety) describe the output.

A schema with transforms usually has no JSON Schema form, so the module can't coerce its input. It receives the raw values, which on Nitro 2 includes parsed numbers and booleans. Accept both, and parse in the schema so the code that reads the config doesn't have to:

```ts [runtime-config.schema.ts]
const runtimeBoolean = v.pipe(
  v.union([v.boolean(), v.picklist(['true', 'false'])]),
  v.transform(value => value === true || value === 'true'),
)
```

An asynchronous schema works too. Request handlers and Nuxt rendering wait for its result. Nitro runs server plugins synchronously, though, so a plugin that reads `useSafeRuntimeConfig()` while it initializes needs a synchronous schema.

## Config per request

On Nitro 2, `useRuntimeConfig(event)` returns a copy of the config for that request, and platforms such as Cloudflare Workers fill it from that request's environment. `useSafeRuntimeConfig(event)` returns the checked version:

```ts [server/utils/cube-token.ts]
import type { H3Event } from 'h3'

export function createCubeToken(event: H3Event): string {
  const { cubeJwtSecret } = useSafeRuntimeConfig(event)
  return jwt.sign({ sub: 'basic' }, cubeJwtSecret, { expiresIn: '1d' })
}
```

On a Node server every request has the startup values, so each one gets a copy of the startup result and the schema doesn't run again. When a request's values differ, its config is converted and validated once for that request. Nitro 3 has one config for the whole process, so there `useSafeRuntimeConfig(event)` returns the same object as `useSafeRuntimeConfig()`.


## Sitemap

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