Environment Nuxt 4

• https://nuxt.com/docs/4.x/guide/going-further/runtime-config#environment-variables

• En nuxt.config.ts, defines la sección runtimeConfig. Puedes separar configuraciones:

  • Privadas (solo servidor)
  • Públicas (cliente y servidor)

• Para usar variables de entorno que reemplacen estos valores en tiempo de ejecución, deben cumplir 2 requisitos:

  1. Deben estar definidas en runtimeConfig.
  2. El nombre de la variable debe seguir esta convención: empezar con NUXT_, usar _ para separar niveles y reflejar la misma estructura.

• Ejemplo de configuración y .env:

  NUXT_API_SECRET=api_secret_token
  NUXT_PUBLIC_API_BASE=https://nuxtjs.org

  // nuxt.config.ts
  export default defineNuxtConfig({
    runtimeConfig: {
      apiSecret: "", // será sustituido por NUXT_API_SECRET
      public: {
        apiBase: "", // será sustituido por NUXT_PUBLIC_API_BASE
      },
    },
  });

• Acceso a la configuración desde el código:

  • Cliente (Vue): solo puedes ver public (y app) via useRuntimeConfig().
  • Servidor: puedes acceder al config completo, pero es solo lectura.

Tutorial paso a paso

1. Configuración del archivo .env

Crea un archivo .env en la raíz del proyecto (y no lo subas al repositorio):

NUXT_API_SECRET=12345-privada-secreta
NUXT_PUBLIC_API_BASE=https://api.miapp.com

2. Configura runtimeConfig en nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: "", // privada: sólo servidor
    public: {
      apiBase: "", // pública: cliente + servidor
    },
  },
});

Esto asegura que las variables estén disponibles tanto en desarrollo como en producción y que se puedan sobrescribir en ejecución mediante las variables .env con prefijo NUXT_.

3. Cómo consumir estas variables

a) En un componente Vue (cliente/SSR):

<script setup lang="ts">
const config = useRuntimeConfig();
console.log("Base API (cliente):", config.public.apiBase);
// config.apiSecret NO está disponible aquí
</script>

b) En un endpoint Server (/server/api/...):

export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event);
  console.log("API base:", config.public.apiBase); // sí está disponible
  console.log("API secret:", config.apiSecret); // solo servidor
});

¿Por qué usar Runtime Config?

Característica	Beneficio
Privadas vs públicas	Asegura que datos sensibles no lleguen al cliente
Variables con NUXT_	Permiten sobrescribir configuraciones en runtime sin rebuild
Acceso diferenciado	public desde cliente; apiSecret solo en servidor

Código completo de ejemplo

Archivo .env:

NUXT_API_SECRET=mi-secreta-clave-2025
NUXT_PUBLIC_API_BASE=https://api.miapp.com

nuxt.config.ts:

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: "",
    public: {
      apiBase: "",
    },
  },
});

Componente Vue:

<script setup lang="ts">
const config = useRuntimeConfig();
console.log("API base en cliente:", config.public.apiBase);
// config.apiSecret – no disponible
</script>

Endpoint API:

export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event);
  // Solo en servidor
  return {
    base: config.public.apiBase,
    secret: config.apiSecret,
  };
});