75 lines
3.3 KiB
Markdown
75 lines
3.3 KiB
Markdown
# 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`).
|
|
|
|
```env
|
|
# ==========================================
|
|
# 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`):
|
|
|
|
```typescript
|
|
// 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(', ')}`);
|
|
}
|
|
}
|
|
```
|