nuxt-safe-runtime-config

Nuxt Safe Runtime Config
Validate Nuxt runtime config with Valibot, Zod, ArkType or an annotated .env.example, and read it through a typed composable.
🔗 Related Nuxt RFC: Enable Standard Schema Validation in Nuxt Config
!TIP Nuxt 5 checks runtime config types itself. Point this module at a schema file and Nuxt types
useRuntimeConfig()from it, while the module runs the URL formats, ranges, patterns and refinements Nuxt skips. See Nuxt 5.
On Nuxt 4, useRuntimeConfig() returns whatever ends up in runtime config. Nothing checks that NUXT_DATABASE_URL is set or that NUXT_PUBLIC_REPLAY_ENABLED=false arrives as false. This module validates runtime config against a schema while you build and again when the server starts, and useSafeRuntimeConfig() returns the values typed from that schema.
Quick start
npx nuxi module add nuxt-safe-runtime-config
// nuxt.config.ts
import * as v from 'valibot'
export default defineNuxtConfig({
modules: ['nuxt-safe-runtime-config'],
runtimeConfig: {
databaseUrl: '',
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(),
}),
}),
},
})
// server/api/report.post.ts
export default defineEventHandler((event) => {
const config = useSafeRuntimeConfig(event)
config.databaseUrl // string
config.public.replayEnabled // boolean, also from NUXT_PUBLIC_REPLAY_ENABLED=false
})
If the server starts without a valid NUXT_DATABASE_URL, it stops before serving a request:
[safe-runtime-config] Runtime validation failed: #: Property "databaseUrl" does not match schema., #/databaseUrl: String does not match format "uri".
What it does
- Build or runtime validation with any Standard Schema library
- Coercion of
NUXT_*strings to the booleans, numbers, enums and JSON values your schema expects, and schema modules for transforms - Generated types for
useSafeRuntimeConfig()in the app and inserver/ .env.exampleas the schema (experimental), so builds need no secrets- An ESLint rule that migrates
useRuntimeConfig()calls - A Nitro module for Nitro apps without Nuxt
Supports Nuxt 4 and the Nuxt 5 nightly, on Nitro 2 and 3.
Contribution
Local development
# Install dependencies
pnpm install
# Generate type stubs
pnpm run dev:prepare
# Develop with the playground
pnpm run dev
# Build the playground
pnpm run dev:build
# Run ESLint
pnpm run lint
# Run Vitest
pnpm run test
pnpm run test:watch
Releases go through uppt. Every push to main updates a draft release/vX.Y.Z PR built from conventional commits. Merging it tags the version, creates the GitHub release, and publishes the package to npm through OIDC trusted publishing. If publishing fails after the tag exists, run gh workflow run release.yml --ref vX.Y.Z.