nuxt-safe-runtime-config
nuxt-safe-runtime-config

Validate runtime config with Standard Schema at build or runtime, with optional Shelve secrets integration.

Nuxt Safe Runtime Config: runtime config you can trust

Nuxt Safe Runtime Config

Validate Nuxt runtime config with Valibot, Zod, ArkType or an annotated .env.example, and read it through a typed composable.

Docs

npm version npm downloads License Nuxt compatibility

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

!TIP Nuxt 5 checks runtime config types itself. Point this module at a schema file and Nuxt types useRuntimeConfig() from it, while the module runs the URL formats, ranges, patterns and refinements Nuxt skips. See Nuxt 5.

On Nuxt 4, useRuntimeConfig() returns whatever ends up in runtime config. Nothing checks that NUXT_DATABASE_URL is set or that NUXT_PUBLIC_REPLAY_ENABLED=false arrives as false. This module validates runtime config against a schema while you build and again when the server starts, and useSafeRuntimeConfig() returns the values typed from that schema.

Quick start

npx nuxi module add nuxt-safe-runtime-config
// nuxt.config.ts
import * as v from 'valibot'

export default defineNuxtConfig({
  modules: ['nuxt-safe-runtime-config'],
  runtimeConfig: {
    databaseUrl: '',
    public: { apiBase: 'https://api.example.com', replayEnabled: false },
  },
  safeRuntimeConfig: {
    $schema: v.object({
      databaseUrl: v.pipe(v.string(), v.url()),
      public: v.object({
        apiBase: v.pipe(v.string(), v.url()),
        replayEnabled: v.boolean(),
      }),
    }),
  },
})
// server/api/report.post.ts
export default defineEventHandler((event) => {
  const config = useSafeRuntimeConfig(event)
  config.databaseUrl // string
  config.public.replayEnabled // boolean, also from NUXT_PUBLIC_REPLAY_ENABLED=false
})

If the server starts without a valid NUXT_DATABASE_URL, it stops before serving a request:

[safe-runtime-config] Runtime validation failed: #: Property "databaseUrl" does not match schema., #/databaseUrl: String does not match format "uri".

What it does

Supports Nuxt 4 and the Nuxt 5 nightly, on Nitro 2 and 3.

Contribution

Local development
# 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

Releases go through uppt. Every push to main updates a draft release/vX.Y.Z PR built from conventional commits. Merging it tags the version, creates the GitHub release, and publishes the package to npm through OIDC trusted publishing. If publishing fails after the tag exists, run gh workflow run release.yml --ref vX.Y.Z.