Migrating to Nuxt 3 runtimeConfig: which keys silently become public?

Answer

In Nuxt 3 only the keys placed under runtimeConfig.public are sent to the browser; all other top‑level keys remain server‑only and are replaced with undefined in client‑side useRuntimeConfig(). This matches the Nuxt 2 split of publicRuntimeConfig and privateRuntimeConfig.

1. Verifying what reaches the browser

After a production build (npx nuxi build) the public config is embedded in the client payload, so checking both the runtime object and the built files shows exactly what ships:

1. Search the build output for a known secret value or its key name:

# replace with a value you know is only server‑side
grep -r "sk_live_test123" .output/public .output/nuxt
grep -r "apiSecret" .output/public

1. Load the built app and open DevTools → Console, then inspect window.__NUXT__. The runtimeConfig property inside that object lists every key that was serialized to the client.

These two steps together are reliable for detecting leaks that end up in the payload or inlined HTML. The only blind spot is secrets that appear in server‑rendered markup, API responses, or source maps; those must be checked separately.

2. Effect of NUXT_PUBLIC_* overrides

The environment‑variable override mechanism maps NUXT_PUBLIC_* to runtimeConfig.public.* using underscore‑to‑camel conversion. An override only takes effect when the target key already exists under runtimeConfig.public in nuxt.config.ts. An undeclared variable such as NUXT_PUBLIC_FOO=leak will not create a new public entry.

However, the matching behavior has changed across Nuxt 3 minor releases, so you should verify it on the exact version you are using:

NUXT_PUBLIC_UNDECLARED_PROBE=leak-test npx nuxi build
grep -r "leak-test" .output/public

If the grep returns nothing, the variable is ignored on your version. The real risk is the opposite direction: a NUXT_PUBLIC_* variable that overrides an existing public key with a credential value, or a developer manually placing a secret under public. Both are silent because Nuxt does not warn about secret‑looking names in the public block.

3. Auditing for accidental public secrets

There is no official Nuxt lint rule for this pattern. Teams typically adopt one or more of the following lightweight checks:

• Naming policy: prohibit keys that match /secret|token|password|private|key/i from appearing inside the public object; enforce in code review.
• CI gate: a build step that fails if such a key is found, for example:

# fail if credential‑named keys sit in the public block
if grep -Pzo 'public:\s*\{[^}]*(?i:secret|token|password)' nuxt.config.ts; then
  echo "Secret‑like key found in runtimeConfig.public"
  exit 1
fi

• Post‑build secret scan: run the grep from question 1 in CI, injecting a canary secret via an environment variable to prove that server‑only values never reach .output/public.

Bottom line

Only runtimeConfig.public reaches the browser. Verify with window.__NUXT__ and a recursive grep of the build output (including .output/nuxt for rendered payloads). Treat NUXT_PUBLIC_* as a public‑value‑only channel and confirm on your Nuxt version whether undeclared overrides are ignored. Add a naming‑policy or CI check to catch credential‑named keys that end up in the public block.