Runtime Config

runtimeConfig in nuxt.config exposes secrets to the server and public values to both client and server, with environment variables overriding them at runtime.

4 min read Level 2/5 #nuxt#config#env

What you'll learn

Define a runtimeConfig block with private and public keys in nuxt.config
Read values with useRuntimeConfig in pages and server routes
Override defaults at runtime via NUXT_ prefixed environment variables

Hardcoding API keys and URLs leaks secrets and breaks portability. runtimeConfig separates build-time defaults from runtime values, with a clean split between server-only and public.

Define It

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '',
    public: {
      apiBase: 'https://api.example.com',
    },
  },
})

Anything outside public is server-only. The public block is bundled into the client payload, so never put secrets there.

Read It

<script setup lang="ts">
const cfg = useRuntimeConfig()
const url = cfg.public.apiBase
</script>

In a server route, you can also read the private keys:

// server/api/secret.ts
export default defineEventHandler(() => {
  const cfg = useRuntimeConfig()
  return { secret: cfg.apiSecret }
})

Override With Env Vars

Runtime config values are overridable at runtime by environment variables prefixed with NUXT_. Camel-cased keys become uppercase snake-case:

NUXT_API_SECRET=sk-live-... \
NUXT_PUBLIC_API_BASE=https://api.prod.com \
node .output/server/index.mjs

This means the same build can ship to staging and production with different config.

When to Use What

Build-time only, never changes — use a const or appConfig.
Runtime, public — runtimeConfig.public.
Runtime, secret — top-level runtimeConfig (server only).

Plugins →