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
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