Getting Started

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

Installation

npx nuxi module add nuxt-safe-runtime-config

Quick Example

Define a schema with your preferred library:

import { number, object, optional, string } from 'valibot'

const runtimeConfigSchema = object({
  public: object({
    apiBase: string(),
    appName: optional(string()),
  }),
  databaseUrl: string(),
  secretKey: string(),
  port: optional(number()),
})

import { z } from 'zod'

const runtimeConfigSchema = 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'

const runtimeConfigSchema = type({
  'public': {
    'apiBase': 'string',
    'appName?': 'string',
  },
  'databaseUrl': 'string',
  'secretKey': 'string',
  'port?': 'number',
})

Configure in nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-safe-runtime-config'],

  runtimeConfig: {
    databaseUrl: process.env.DATABASE_URL || '',
    secretKey: process.env.SECRET_KEY || '',
    port: Number.parseInt(process.env.PORT || '3000'),
    public: {
      apiBase: process.env.PUBLIC_API_BASE || 'https://api.example.com',
      appName: 'My App',
    },
  },

  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,
  },
})

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

Configuration