---
title: "Migrate to ViteHub Env"
description: "Replace runtime config and this module with @vite-hub/env on Nuxt 5. A codemod rewrites the config and the call sites, and reports what it couldn't."
canonical_url: "https://nuxt-safe-runtime-config.onmax.me/guide/migrate-to-vitehub-env"
---
# Migrate to ViteHub Env

> Replace runtime config and this module with @vite-hub/env on Nuxt 5. A codemod rewrites the config and the call sites, and reports what it couldn't.

[ViteHub Env](https://vitehub.dev/docs/env) (`@vite-hub/env`) replaces runtime config on Nuxt 5 instead of checking it. If you want to keep runtime config, see [Nuxt 5](https://nuxt-safe-runtime-config.onmax.me/guide/nuxt-5) instead. With Env you still declare each value once and read it typed. The differences:

- Server code reads `useServerEnv(event)` and app code reads `usePublicEnv()`, and the same API works in Vite and Nitro apps.
- A secret is a `SecretEnv` that prints `<redacted>` until you call `.unseal()`.
- Env reads the same [`.env.example` format](https://nuxt-safe-runtime-config.onmax.me/reference/env-spec), so an `envSchema` app keeps its file as it is.
- `vitehub env check` lists every declared variable and whether it is set, without printing values.

## Run the codemod

The codemod and `vite-hub` need Node.js 24.15 or later, even if your app runs on Node.js 22 today. Upgrade first.

<steps>

### Preview the changes

```bash
npx @vite-hub/codemods nuxt-safe-runtime-config --dry-run
```

`--dry-run` prints the diff for each file and the report, and writes nothing. Pass a directory as the last argument when the app isn't in the current one.

### Apply them

```bash
npx @vite-hub/codemods nuxt-safe-runtime-config
```

### Install and check

```bash
pnpm install
npx nuxi prepare
```

Then run your typecheck and work through the [follow-ups](#follow-ups) in the report.

</steps>

## What the codemod changes

In `nuxt.config.ts` it replaces `nuxt-safe-runtime-config` with `vite-hub/nuxt` in `modules`, moves your declarations to `vitehub.env` and removes `safeRuntimeConfig`. In `package.json` it removes this module and adds `vite-hub`.

### An `envSchema` app

The `.env.example` stays as it is. `prefix: 'NUXT_'` keeps the variable names and the same public split:

```ts [nuxt.config.ts]
import { envSchema } from '@vite-hub/env/vite'

export default defineNuxtConfig({
  modules: ['vite-hub/nuxt'],
  vitehub: {
    preset: 'node',
    env: envSchema(new URL('./.env.example', import.meta.url), { prefix: 'NUXT_' }),
  },
})
```

### A `$schema` app

The codemod loads your schema, converts it to JSON Schema and writes one Env declaration per value. Each value keeps its `NUXT_*` name, and literal defaults stay.

<code-group>

```ts [Before]
export default defineNuxtConfig({
  modules: ['nuxt-safe-runtime-config'],
  runtimeConfig: {
    apiSecret: '',
    maxRetries: 3,
    featureEnabled: false,
    public: { apiBase: 'https://api.example.com' },
  },
  safeRuntimeConfig: {
    $schema: v.object({
      apiSecret: v.pipe(v.string(), v.minLength(16)),
      maxRetries: v.number(),
      featureEnabled: v.boolean(),
      public: v.object({ apiBase: v.pipe(v.string(), v.url()) }),
    }),
  },
})
```

```ts [After]
import { env } from 'vite-hub/env'

export default defineNuxtConfig({
  modules: ['vite-hub/nuxt'],
  vitehub: {
    preset: 'node',
    env: {
      public: {
        apiBase: env({ default: 'https://api.example.com', mode: 'build', source: env.source('NUXT_PUBLIC_API_BASE') }),
      },
      server: {
        apiSecret: env({ secret: true, source: env.source('NUXT_API_SECRET') }),
        maxRetries: env.number({ default: 3, source: env.source('NUXT_MAX_RETRIES') }),
        featureEnabled: env.boolean({ default: false, source: env.source('NUXT_FEATURE_ENABLED') }),
      },
    },
  },
})
```

</code-group>

Server fields with credential-like names, such as `secret`, `token`, `password`, `key` or a database URL, become `secret: true`.

### Your code

```ts [server/api/config.get.ts]
// Before
const config = useSafeRuntimeConfig(event)

// After
import { useServerEnv } from '#vitehub/env/server'
const config = useServerEnv(event)
```

In app code, `useSafeRuntimeConfig()` becomes `usePublicEnv()` from `#vitehub/env/public`, and `config.public.apiBase` becomes `config.apiBase`.

<warning>

Env fixes public values at build time. This module applied `NUXT_PUBLIC_*` overrides when the server started, so set those variables before you build. Server values are still read when the server runs.

</warning>

## Follow-ups

The report lists each change the codemod couldn't make, with its `file:line`:

- `config.apiSecret` is now a `SecretEnv<string>`. Call `.unseal()` where the code needs the raw value.
- Code-first Env declarations drop minimum lengths, patterns, URL formats, transforms and refinements. Check those values in code, or move to a `.env.example` with `envSchema()`, which keeps length, range, integer and URL checks.
- JSON arrays, objects and unions stay in `runtimeConfig`. Read them with `useRuntimeConfig()`, or declare them in a `.env.example`.
- `vite-hub/nuxt` needs a deployment preset. The codemod copies `nitro.preset` when it can, and sets `node` otherwise.
- Calls it couldn't follow, such as a config object passed to another function, or a `useRuntimeConfig()` read of a key that moved.
- `nuxt-safe-runtime-config/eslint` in your ESLint config, which you remove by hand.

The codemod doesn't cover the [standalone Nitro module](https://nuxt-safe-runtime-config.onmax.me/guide/nitro).


## Sitemap

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