04 — Gestión de Variables de Entorno y Configuración

Estándar obligatorio de variables públicas, privadas y archivos .env en Next.js

Uso: El manejo inadecuado de claves de entorno puede exponer información confidencial en el navegador del cliente. Esta guía define cómo gestionar de forma segura e incremental las configuraciones en Next.js.

1. Alcance de Variables: Privadas vs Públicas

Next.js por defecto protege todas las variables cargadas en el proceso de Node.js. El cliente (navegador) no tiene forma de leerlas a menos que se expongan de manera explícita.

1.1 Variables del Servidor (Privadas)

No llevan prefijo. Solo están disponibles en Server Components, API Routes, Middleware, e Inbound/Outbound logs del lado del servidor.

Ejemplos: Llaves secretas de cifrado Kong, URLs directas de red de Spring Boot, contraseñas de servicio.
NUNCA intentes acceder a ellas desde componentes declarados con use client. Retornarán undefined.

1.2 Variables del Cliente (Públicas)

Deben llevar obligatoriamente el prefijo NEXT_PUBLIC_. Next.js las inyecta en el bundle de Javascript durante el build, haciéndolas accesibles desde cualquier navegador.

Ejemplos: URL pública de API routes locales, Google Analytics keys, variables de tema visual.
REGLA DE ORO: Nunca asignes llaves secretas o tokens de servicio a variables con prefijo NEXT_PUBLIC_.

2. Matriz de Configuración del Proyecto

Las variables estándar que deben estar definidas en tu entorno local son:

Variable	Tipo	Propósito	Ejemplo
`NODE_ENV`	Privada	Define el entorno actual	`development` / `production`
`API_URL_SERVER`	Privada	Endpoint directo de la red interna del backend Spring Boot	`https://api-internal.tudominio.com/api`
`NEXT_PUBLIC_API_URL`	Pública	URL de la API local de Next.js para peticiones del cliente	`http://localhost:3000/api`
`KONG_SECRET_KEY`	Privada	Clave de cifrado perimetral de datos	`k-secret-key-321-abc`
`ENABLE_SERVER_LOGS`	Privada	Activa/Desactiva escritura en logs/app.log	`true`

3. Ejemplo de Archivo `.env.local`

Este archivo es de carácter local y no se incluye en git (debe estar en .gitignore).

# ==========================================
# CONFIGURACIÓN DEL SERVIDOR (PRIVADAS)
# ==========================================
NODE_ENV=development
API_URL_SERVER=http://localhost:8080/api
KONG_SECRET_KEY=clave_secreta_para_cifrado_local_32bits
ENABLE_SERVER_LOGS=true

# ==========================================
# CONFIGURACIÓN DEL CLIENTE (PÚBLICAS)
# ==========================================
NEXT_PUBLIC_API_URL=http://localhost:3000/api

4. Validación de Entorno

Para evitar que la aplicación arranque con configuraciones incompletas o corruptas que generen fallos silenciosos, se recomienda validar las variables críticas al inicializar la app (por ejemplo, en lib/config.ts):

// lib/config.ts
const requiredServerEnv = ['API_URL_SERVER', 'KONG_SECRET_KEY'];

export function validateEnvironment() {
  const missing = requiredServerEnv.filter((key) => !process.env[key]);
  
  if (missing.length > 0) {
    throw new Error(`[CRITICAL] Faltan variables de entorno requeridas en el servidor: ${missing.join(', ')}`);
  }
}

3.3 KiB Raw Permalink Blame History