Getting Started
Getting Started
Validate your Nuxt runtime config at build or runtime using Zod, Valibot, ArkType, or any Standard Schema compatible library.
Validate your Nuxt runtime config at build or runtime using Zod, Valibot, ArkType, or any Standard Schema compatible library.
Features
- Build-time validation - catch config errors before deployment
- Runtime validation (opt-in) - validate when server starts
- Auto-generated types -
useSafeRuntimeConfig()is fully typed - ESLint plugin - warns when using untyped
useRuntimeConfig() - Zero runtime overhead - validation at build time only by default
- Shelve integration - fetch secrets from Shelve and inject into runtimeConfig
Installation
npx nuxi module add nuxt-safe-runtime-config
Compatibility
nuxt-safe-runtime-config supports Nuxt 3 and Nuxt 4. It is also tested with Nuxt 4.2+ using future.compatibilityVersion: 5 and with the Nuxt 5 nightly channel (nuxt-nightly@5x).
Runtime validation converts Standard Schema definitions to JSON Schema. The module includes the Valibot and Zod converter dependencies, so applications do not need to install @valibot/to-json-schema or zod-to-json-schema separately.
Quick Example
Define your schema directly in nuxt.config.ts:
import { number, object, optional, string } from 'valibot'
export default defineNuxtConfig({
modules: ['nuxt-safe-runtime-config'],
runtimeConfig: {
databaseUrl: '',
secretKey: '',
port: 3000,
public: { apiBase: 'https://api.example.com', appName: 'My App' },
},
safeRuntimeConfig: {
$schema: object({
public: object({ apiBase: string(), appName: optional(string()) }),
databaseUrl: string(),
secretKey: string(),
port: optional(number()),
}),
},
})
import { z } from 'zod'
export default defineNuxtConfig({
modules: ['nuxt-safe-runtime-config'],
runtimeConfig: {
databaseUrl: '',
secretKey: '',
port: 3000,
public: { apiBase: 'https://api.example.com', appName: 'My App' },
},
safeRuntimeConfig: {
$schema: z.object({
public: z.object({ apiBase: z.string(), appName: z.string().optional() }),
databaseUrl: z.string(),
secretKey: z.string(),
port: z.number().optional(),
}),
},
})
import { type } from 'arktype'
export default defineNuxtConfig({
modules: ['nuxt-safe-runtime-config'],
runtimeConfig: {
databaseUrl: '',
secretKey: '',
port: 3000,
public: { apiBase: 'https://api.example.com', appName: 'My App' },
},
safeRuntimeConfig: {
$schema: type({
'public': { 'apiBase': 'string', 'appName?': 'string' },
'databaseUrl': 'string',
'secretKey': 'string',
'port?': 'number',
}),
},
})
Use the type-safe composable:
<script setup lang="ts">
const config = useSafeRuntimeConfig()
// config.public.apiBase - string (typed)
// config.secretKey - string (typed)
</script>
Next Steps
- Configuration - all module options
- Type Safety - how auto-generated types work
- Validation - build vs runtime validation