Nuxt · NUXT0090

Do not freeze runtime config environment variables into build options

Finds nuxt.config options outside runtimeConfig whose value comes from a NUXT_ or NITRO_ environment variable that also overrides a declared runtimeConfig key.
NUXT0090vite-doctor/nuxtruntime-configwarnSuggestion

Run this rule

pnpm nuxt doctor --rules nuxt/config/no-runtime-env-in-build-options

Why it matters

nuxt.config runs once, when the app is built, so every option outside runtimeConfig keeps the value the variable had at build time. Nuxt applies NUXT_ variables to runtimeConfig again when the server starts, which is why they are the usual way to configure one build per environment or tenant. An option that reads the same variable gets the build-time value instead, often empty in a Docker build that sets the variable only on the running container. Doctor only reports values whose environment reads are all NUXT_ or NITRO_ variables and at least one of them matches a key declared in runtimeConfig. A fallback to a variable without a NUXT_ or NITRO_ prefix, or passing process.env as a whole, is treated as an intentional build-time source.

Read the value from useRuntimeConfig() where it is used, or set the variable in the build environment when the option has to be fixed at build time.

Example

Read tenant config at runtime

Before

const organization = process.env.NUXT_PUBLIC_ORGANIZATION_CODE

export default defineNuxtConfig({
  runtimeConfig: { public: { organizationCode: organization } },
  piniaPluginPersistedstate: { key: `${organization}:%id` },
})

After

export default defineNuxtConfig({
  runtimeConfig: { public: { organizationCode: '' } },
})

// app/plugins/persisted-state.ts
export default defineNuxtPlugin(({ $pinia }) => {
  const { organizationCode } = useRuntimeConfig().public
  $pinia.use(createPersistedState({ key: id => `${organizationCode}:${id}` }))
})
Copyright © 2026