Nuxt Safe Runtime Config

Validate Nuxt runtime config at build time using Zod, Valibot, ArkType, or any Standard Schema compatible library.

🔗 Related Nuxt RFC: Enable Standard Schema Validation in Nuxt Config

Features

• 🔒  Validate runtime config at build time with Zod, Valibot, ArkType, and more
• 🚀  Works with any Standard Schema compatible library
• 🛠  Only runs during dev/build/generate phases
• ⚡  Zero runtime overhead - validation happens at build time only
• 📝  Does not modify your runtime config or types - only validates them

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add nuxt-safe-runtime-config

Usage

1. Add the module to your nuxt.config.ts:

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

2. Define your runtime config schema using Valibot, Zod, ArkType, or any other Standard Schema compatible 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'
})

3. Configure your Nuxt app:

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

  // Your regular runtime config
  runtimeConfig: {
    databaseUrl: process.env.DATABASE_URL || 'postgresql://localhost:5432/mydb',
    secretKey: process.env.SECRET_KEY || 'default-secret-key',
    port: Number.parseInt(process.env.PORT || '3000'),
    public: {
      apiBase: process.env.PUBLIC_API_BASE || 'https://api.example.com',
      appName: 'My Nuxt App',
    },
  },

  // Add your schema for validation
  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,
  },
})

The module validates your runtime config after environment variables are merged during:

• nuxi dev (development mode)
• nuxi build
• nuxi generate

This means validation happens at runtime initialization, after all NUXT_* environment variables from .env files have been merged into your runtime config. If validation fails, the build process will stop with detailed error messages.

Important Notes

This module only validates your runtime config - it does not modify it. Your native runtimeConfig remains unchanged, and no TypeScript types are modified. The module simply ensures that your runtime configuration matches your schema at build time, helping you catch configuration errors early in the development process.

Error Messages

When validation fails, you'll see detailed error messages like:

Safe Runtime Config: Validation failed!
  1. databaseUrl: This field is required
  2. public.apiBase: Expected string, received undefined
  3. port: Expected number, received string

The module will stop the build process until all validation errors are resolved.

Why This Module?

I wanted to use Valibot for runtime config validation, but Nuxt doesn't currently support Standard Schema. While Nuxt has its own schema validation system, it's primarily designed for module authors and broader Nuxt configuration.

This module focuses specifically on runtime config validation using the Standard Schema specification, allowing you to use your preferred validation library (Valibot, Zod, ArkType, etc.).

The goal is to eventually make Standard Schema a first-class citizen in Nuxt. If this module gains enough adoption, I plan to create a PR to add standardSchema support to Nuxt core.

Contribution

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

# Release new version
pnpm run release