Getting Started
Type Safety
The module generates TypeScript types from your schema, making useSafeRuntimeConfig() fully typed without manual generics in both app and server code.
The module generates TypeScript types from your schema, making useSafeRuntimeConfig() fully typed without manual generics in both app and server code.
How It Works
- Your schema is converted to JSON Schema
- JSON Schema is transformed to TypeScript types
- Types are written to
.nuxt/types/safe-runtime-config.d.ts useSafeRuntimeConfig()returns a typed object
useSafeRuntimeConfig vs useRuntimeConfig
| Composable | Types | Validation |
|---|---|---|
useRuntimeConfig() | Partial, manual | None |
useSafeRuntimeConfig() | Auto-generated from schema | Build + Runtime (opt-in) |
// useRuntimeConfig() - types may not match actual values
const config = useRuntimeConfig()
config.public.apiBase // unknown or manually typed
// useSafeRuntimeConfig() - types inferred from schema
const config = useSafeRuntimeConfig()
config.public.apiBase // string (from your schema)
Type Inference
Types are inferred from your schema's structure:
// Schema
const schema = object({
public: object({
apiBase: string(),
count: optional(number()),
}),
secretKey: string(),
})
// Generated type
interface SafeRuntimeConfig {
public: {
apiBase: string
count?: number
}
secretKey: string
}
Server vs Client
On the server (including server/api and server/utils), you get the full config. On the client, only public properties are available:
// Server
const config = useSafeRuntimeConfig()
config.secretKey // available
// Client
const config = useSafeRuntimeConfig()
config.secretKey // undefined (private keys not exposed)
config.public.apiBase // available
// server/utils/config.ts
export function getServerConfig() {
const config = useSafeRuntimeConfig()
return {
secretKey: config.secretKey,
apiBase: config.public.apiBase,
}
}
Generated Types Location
Types are stored in .nuxt/types/safe-runtime-config.d.ts and automatically included via Nuxt's type augmentation.
Run nuxi prepare to regenerate types after schema changes.