Server-Side Runtime Config Access vs Client-Side Hydration in Nuxt

Answer to the Question

In a Nuxt 3 production build, the only way to make an environment variable available to both the server‑side rendering and the client‑side hydration is to declare it in publicRuntimeConfig (or runtimeConfig.public in nuxt.config.ts). Adding the key to publicRuntimeConfig guarantees that the value is bundled into the client JavaScript and can be accessed via useRuntimeConfig() after hydration. Variables that live only in serverRuntimeConfig are never shipped to the browser, so any direct process.env reference will be undefined in client code.

Why process.env Works Only in Development

During nuxt dev the Vite dev server injects process.env into both bundles. In a production build, Vite strips all process.env references that are not explicitly exposed via publicRuntimeConfig to avoid leaking secrets.

Recommended Steps for a Production‑Ready Setup

1. Define the variable in your .env file, e.g. MY_API_URL=https://api.example.com.
2. Expose it in nuxt.config.ts:

   export default defineNuxtConfig({
     runtimeConfig: {
       public: {
         apiUrl: process.env.MY_API_URL
       }
     }
   })
   

3. In any component, use const config = useRuntimeConfig() and read config.public.apiUrl. This value is present during SSR and after hydration.
4. For server‑only secrets (e.g. database passwords), keep them in runtimeConfig without the public flag and access them only in server‑only hooks or API routes.

Accessing the Value in Different Contexts

Context	How to Access
asyncData / setup (before hydration)	const config = useRuntimeConfig() – config.public.apiUrl is available.
Mounted hook / client‑only code	Same useRuntimeConfig(); the public key is still available.
Server‑only code (e.g. serverMiddleware)	Use useRuntimeConfig() or process.env.MY_API_URL directly.

Security & Caching Notes

• Never put secrets in publicRuntimeConfig – they will be visible in the browser bundle.
• Changing a public config value requires a rebuild or a full page reload to see the new value on the client.
• If you need to expose a server‑only value to the client after hydration, expose it through an authenticated API endpoint instead of storing it in localStorage.

Verification Checklist

• Run nuxt dev, log useRuntimeConfig() in asyncData and mounted() – both should show public.apiUrl.
• Build with nuxt build and nuxt preview, then open the browser console and confirm useRuntimeConfig() returns the public key.
• Try accessing a serverRuntimeConfig key on the client; it should be undefined.

Missing Diagnostic Detail?

If you are unsure whether a particular variable should be public or server‑only, let me know its intended use (e.g., API endpoint, secret key, feature flag). That will help refine the recommendation further.