Nuxt Environment Variables: runtimeConfig to NUXT_

How a key becomes a name

Nitro walks runtimeConfig and, for every key, joins the path to it with underscores, runs that through scule's snakeCase, upper-cases it and adds a prefix. A new word starts at a separator (-, _, . or /) and wherever a lowercase letter meets a capital. A run of capitals stays one word, except that its last capital starts the next word when a lowercase letter follows, so myAPIKey becomes MY_API_KEY.

Because separators and case changes count the same, proMax, pro-max and pro_max all become PRO_MAX. Nitro looks each name up on its own, so one variable then sets every key that shares it. Objects have names too: NUXT_PUBLIC set to a JSON object merges into the whole public block.

Why a variable is ignored

Nitro only overrides keys that exist in the built config. Declare every key you want to set, even as an empty string. Nuxt turns null and undefined into empty strings, so those count as declared.

• A name that is off by one underscore matches nothing, and Nitro says nothing about it.
• A default such as process.env.API_SECRET is read once, at build time. At runtime only the NUXT_ name for that key changes it.
• nuxt dev, nuxt build and nuxt generate load .env, and nuxt preview hands it to the built server for a local check. In production the server never reads it, so set the variables where it runs.
• In server code, useRuntimeConfig(event) applies the variables for each request. Without the event, Nitro hands back the config it worked out when the server first loaded.

app.config.ts, appConfig and most of the app block in nuxt.config are fixed at build time. Of the app options, only baseURL, buildAssetsDir and cdnURL reach runtimeConfig.app, and the Nuxt docs advise against changing buildAssetsDir at runtime.

Values arrive parsed

Nitro runs every value through destr before it touches the config, so true arrives as a boolean, 12345 as a number and {"beta":true} as an object. A value wrapped in literal double quotes stays a string with the quotes removed. In a .env file, put single quotes around those double quotes, because dotenv strips one layer of quotes itself.

What happens next depends on the key:

• a plain key takes the parsed value, and an empty value sets it to an empty string
• an object key merges a JSON object into itself and is replaced by anything else
• an array is replaced whole
• null and undefined leave the default in place

Public keys and Nuxt's own keys

Everything under runtimeConfig.public reaches the browser in the page payload, and so does runtimeConfig.app, which Nuxt uses itself. The Nuxt docs reserve top-level keys that start with app for Nuxt. Nuxt 4.6 added appSecret, a server-only root secret that modules derive their own secrets from, and you can set it with NUXT_APP_SECRET without declaring it.

On Cloudflare Workers

The Worker reads vars and secrets as environment variables under the same names. Cloudflare hands a vars value written as a JSON object to process.env as its raw JSON text, and destr parses it back, so it merges into an object key. Text values are parsed the same way, so a text var of digits arrives as a number unless it keeps the inner double quotes the Wrangler template writes.