Configuration

All options for safeRuntimeConfig in your nuxt.config.ts.

Options Reference

Option	Type	Default	Description
`$schema`	`StandardSchemaV1`	-	Your validation schema (required)
`validateAtBuild`	`boolean`	`true`	Validate during dev/build
`validateAtRuntime`	`boolean`	`false`	Validate when server starts
`onBuildError`	`'throw' \| 'warn' \| 'ignore'`	`'throw'`	Build validation error behavior
`onRuntimeError`	`'throw' \| 'warn' \| 'ignore'`	`'throw'`	Runtime validation error behavior
`logSuccess`	`boolean`	`true`	Log successful validation
`logFallback`	`boolean`	`true`	Log JSON Schema fallback warnings
`jsonSchemaTarget`	`string`	`'draft-2020-12'`	JSON Schema version for runtime

Example Configuration

nuxt.config.ts

export default defineNuxtConfig({
  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,

    // Validation timing
    validateAtBuild: true,    // default
    validateAtRuntime: false, // opt-in

    // Error handling
    onBuildError: 'throw',    // stop build on error
    onRuntimeError: 'warn',   // log warning, don't crash

    // Logging
    logSuccess: true,
    logFallback: true,

    // JSON Schema
    jsonSchemaTarget: 'draft-2020-12',
  },
})

Error Behaviors

`'throw'` (default)

Stops the build or throws an error at runtime. Recommended for catching issues early.

`'warn'`

Logs a warning but continues. Useful during migration or when some values are expected to be missing in development.

`'ignore'`

Silently continues. Use sparingly.

JSON Schema Target

The jsonSchemaTarget option controls which JSON Schema draft to use for runtime validation. Options:

'draft-2020-12' (default) - latest, best compatibility
'draft-2019-09' - if your tools require it
'draft-07' - legacy support

Runtime validation uses @cfworker/json-schema, a lightweight (~8KB) validator that works on all runtimes including edge.

Getting Started

Type Safety