How do you securely manage private/public config variables in Nuxt 4, and what's the difference between runtimeConfig vs app.config?

Nuxt 4 separates runtimeConfig for secure environment variables from app.config for reactive theme/UI settings. runtimeConfig supports private server-only keys (NUXT_SECRET_ prefix) and public client-safe values (NUXT_PUBLIC_), while app.config handles static theme objects with HMR but no env var access. Private configs never reach client; public configs hydrate safely.​

runtimeConfig supports environment variables (private/public), exposes only public subset to client, keeps private keys server-side, but requires restart for changes. app.config is static-only (no env vars), exposes full object to client, SSR-safe for all data, and supports hot reload.

Complete Implementation:-

Step 1: nuxt.config.ts

Code

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: 'fallback',      // Server-only (NUXT_API_SECRET)
    public: {
      apiUrl: '/api',           // Client-safe (NUXT_PUBLIC_API_URL)
      version: '1.0.0'
    }
  }
})
      

Step 2: Environment (.env)

Code

NUXT_API_SECRET=supersecret
NUXT_PUBLIC_API_URL=https://api.com
      

Step 3: Usage Patterns

Code

<script setup>
// Runtime config (env-driven)
const { public: { apiUrl } } = useRuntimeConfig()
// apiUrl: Client-safe only

// App config (theming)
const { theme } = useAppConfig()
// theme: Full object, HMR-enabled
</script>
      

Step 4: Server Access

Code

// server/api/data.get.ts
export default defineEventHandler(async () => {
  const config = useRuntimeConfig()
  // Full access: config.apiSecret + config.public.apiUrl
})