Validation

The module validates your runtime config to catch configuration errors early. By default, validation runs at build time only.

Build-time Validation (Default)

With default settings, validation runs at:

• Dev start - when running nuxt dev
• Build completion - when running nuxt build

export default defineNuxtConfig({
  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,
    validateAtBuild: true, // default
  },
})

Build-time validation uses your schema library directly. It catches:

• Missing required values
• Type mismatches
• Invalid formats

Benefits:

• Zero runtime overhead
• Fail fast before deployment
• CI/CD friendly
• Validation library not bundled in production

Runtime Validation (Opt-in)

Runtime validation catches issues that only appear in production, like environment variables set differently than during build.

export default defineNuxtConfig({
  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,
    validateAtRuntime: true,
  },
})

When enabled:

1. Module generates JSON Schema from your Standard Schema
2. A Nitro plugin validates useRuntimeConfig() on cold start
3. Uses @cfworker/json-schema (~8KB, edge-compatible)

What it catches:

• Missing env vars in production (DATABASE_URL not set)
• Type mismatches (NUXT_PORT=abc when expecting number)
• Invalid values at runtime

Error Handling

Control how validation errors are handled:

export default defineNuxtConfig({
  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,
    onBuildError: 'throw', // 'throw' | 'warn' | 'ignore'
    onRuntimeError: 'throw', // 'throw' | 'warn' | 'ignore'
  },
})

• 'throw' (default) - stops build or crashes server
• 'warn' - logs warning, continues
• 'ignore' - silent

Error Messages

When validation fails:

[safe-runtime-config] Validation failed!
  1. databaseUrl: Invalid type: Expected string but received undefined
  2. public.apiBase: Invalid type: Expected string but received undefined
  3. port: Invalid type: Expected number but received string

Both Modes

Enable both for maximum safety:

export default defineNuxtConfig({
  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,
    validateAtBuild: true, // catch dev errors
    validateAtRuntime: true, // catch prod errors
  },
})