Runtime Config

Nuxt Kit provides a set of utilities to help you access and modify Nuxt runtime configuration.

useRuntimeConfig

At build-time, it is possible to access the resolved Nuxt runtime config.

Matching environment variables are applied and converted in the same way as at runtime. Schemas declared in runtimeConfig are replaced by their default values.

Prefer useRuntimeConfig() to reading nuxt.options.runtimeConfig in a module. nuxt.options.runtimeConfig holds the default values only, without environment variables applied.

Type

function useRuntimeConfig (): Record<string, unknown>

updateRuntimeConfig

It is also possible to update runtime configuration. This will be merged with the existing runtime configuration, and if Nitro has already been initialized it will trigger an HMR event to reload the Nitro runtime config.

Schemas

A value passed to updateRuntimeConfig can be a schema, which sets the type of the value and its default:

import { defineNuxtModule, updateRuntimeConfig } from '@nuxt/kit'
import { z } from 'zod'

export default defineNuxtModule({
  setup () {
    updateRuntimeConfig({
      myModule: z.object({
        apiKey: z.string(),
        retries: z.number().default(3),
      }),
    })
  },
})

The schema is replaced by its default value straight away, so later modules read plain values from nuxt.options.runtimeConfig. A value the user has set at the same path, such as runtimeConfig.myModule.apiKey in their nuxt.config, is kept and becomes the default of the schema. A schema the user has declared at the same path takes precedence over the module's.

Assigning a schema to nuxt.options.runtimeConfig directly throws an error.

On versions of Nuxt without support for runtime config schemas, a schema is replaced by its default value and is not validated. A required value without a default becomes an empty string, so an environment variable can still override it.

Type

function updateRuntimeConfig (config: Record<string, unknown>): void | Promise<void>