Updated Jan 2026: Simplified proposal. The original blocker (JSON Schema conversion) is now resolved.

TL;DR

import { z } from 'zod'

export default defineNuxtConfig({
  runtimeConfig: {
    secretKey: '',
    public: { apiBase: '' },

    $schema: z.object({
      secretKey: z.string().min(1),
      public: z.object({ apiBase: z.string().url() })
    })
  }
})

Build fails if config invalid. Types auto-generated for useRuntimeConfig().

What Changed

The main blocker raised by @sandros94 ("lack of standardized JSON Schema conversion") is now resolved:

New in Standard Schema spec: StandardJSONSchemaV1 interface with targets draft-2020-12, draft-07, openapi-3.0.

Proof of concept: nuxt-safe-runtime-config implements this pattern today.

Proposal

runtimeConfig.$schema

Accept a Standard Schema object that:

1. Validates at build time (nuxi dev/build) after env vars merge
2. Generates types for useRuntimeConfig() automatically
3. Partial validation - only declared keys checked, others ignored

Detection Logic

if (schema?.['~standard']?.validate) {
  // Standard Schema - validate and generate types
} else if (typeof schema === 'object') {
  // JSON Schema - existing behavior
}

Type Generation

Convert schema to JSON Schema, then to TypeScript:

// .nuxt/types/runtime-config.d.ts
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    secretKey: string
    public: { apiBase: string }
  }
}

JSON Schema Fallback

async function getJSONSchema(schema: StandardSchemaV1) {
  // 1. Try native (Zod v4)
  if (schema['~standard'].jsonSchema?.output) {
    return schema['~standard'].jsonSchema.output({ target: 'draft-2020-12' })
  }
  // 2. Fallback (Valibot, ArkType, etc.)
  return toJsonSchema(schema) // @standard-community/standard-json
}

Error Output

[nuxt] runtimeConfig validation failed:
  - secretKey: String must contain at least 1 character(s)
  - public.apiBase: Invalid url

Scope

In scope:

• runtimeConfig.$schema with Standard Schema
• Build-time validation
• Type inference for useRuntimeConfig()

Out of scope (can be added later):

• Runtime validation (opt-in server startup check)
• Full nuxt.config validation
• Module-level schema extension hook

Implementation

~150 LOC in core:

1. packages/schema/src/types/config.ts - Add $schema?: StandardSchemaV1 to RuntimeConfigInput
2. packages/nuxt/src/core/nuxt.ts - Validate on nuxt:ready + build:done
3. packages/nuxt/src/core/templates.ts - Generate types from schema

Dependencies:

• @standard-schema/spec (types only)
• @standard-community/standard-json (~5KB, fallback)

Questions for Team

1. Naming: $schema (matches existing pattern) or $standardSchema (explicit)?
2. Modules: Should modules be able to extend via schema:runtimeConfig hook?
3. Strictness: Default to partial validation (ignore undeclared) or strict?

References

• Standard Schema spec
• Zod v4 JSON Schema
• Working implementation
• StandardJSONSchemaV1 discussion