Proteger las credenciales y secretos de una aplicación es fundamental para cualquier proyecto profesional. La estrategia más probada en producción y en proyectos open source consiste en separar las llaves sensibles en archivos que nunca se suban al repositorio, mientras se mantiene un archivo de ejemplo versionado que sirve como guía para otros desarrolladores.
¿Cómo funciona el patrón de archivos .env en proyectos reales?
El flujo se basa en dos archivos con roles distintos [0:40]:
- Archivo de ejemplo (
.env.local.example): está versionado en Git, contiene todas las llaves necesarias pero con valores vacíos o ficticios. Su propósito es documentar qué variables requiere el proyecto.
- Archivo real (
.env.local): está ignorado por Git gracias al .gitignore. Contiene los valores reales de las credenciales y cada desarrollador o servidor lo llena de forma independiente.
Esta separación garantiza que, aunque alguien acceda al repositorio en GitHub, nunca verá contraseñas ni tokens reales. Git literalmente tiene "los ojos tapados" frente al archivo .env.local, por lo que cualquier cambio en él pasa desapercibido para el control de versiones.
¿Qué debe contener el archivo de ejemplo?
El .env.local.example lista cada variable con una descripción útil en lugar del valor real [3:20]:
NEXT_PUBLIC_SPACE_ID=your space ID
NEXT_PUBLIC_ACCESS_TOKEN=Necesitas el Contentful access token
Esto sirve como documentación viva para cualquier persona que descargue el proyecto por primera vez. Sabe exactamente qué credenciales necesita conseguir antes de ejecutar la aplicación.
¿Cómo se crea el archivo real con los secretos?
Junto al package.json, se crea .env.local con las mismas llaves pero esta vez con los valores auténticos [4:10]:
NEXT_PUBLIC_SPACE_ID=abc123real
NEXT_PUBLIC_ACCESS_TOKEN=token_secreto_real
Ambos archivos deben coincidir en sus llaves. La única diferencia es que .env.local tiene los valores que la aplicación realmente necesita, mientras que .env.local.example tiene valores dummy o vacíos.
¿Por qué Next.js lee automáticamente el archivo .env.local?
Next.js detecta la presencia de un archivo llamado .env.local en la raíz del proyecto y lo carga automáticamente al iniciar con yarn dev [5:30]. Ya no es necesario pasar las variables manualmente en la línea de comandos.
Esto funciona porque, internamente, Node.js expone todas las variables de entorno a través del objeto process.env [6:10]. Así, dentro del código de la API se accede a los valores de esta forma:
javascript
process.env.NEXT_PUBLIC_SPACE_ID
process.env.NEXT_PUBLIC_ACCESS_TOKEN
El objeto process.env es una característica nativa de Node.js, no exclusiva de Next.js. Probablemente ya has visto process.env.NODE_ENV, que es una variable de entorno que Node.js maneja por defecto para identificar si estás en desarrollo o producción.
¿Qué otros archivos de entorno soporta Next.js?
Además de .env.local, Next.js permite crear archivos especializados por ambiente [7:00]:
.env.stage: para el entorno de staging..env.test: para pruebas automatizadas..env.production: para el entorno de producción.
Cada uno funciona de la misma manera, pero está diseñado para cargarse en su ambiente correspondiente. En la mayoría de aplicaciones, .env.local es más que suficiente para tener control total, sin importar en qué ambiente te encuentres. Solo necesitas colocar los valores adecuados según el entorno que requieras.
Un detalle importante por explorar es la convención de nombres de las variables de entorno en Next.js. El prefijo NEXT_PUBLIC_ tiene un comportamiento especial que determina si una variable estará disponible en el navegador o solo en el servidor, un tema que se aborda en la siguiente sesión.
¿Ya implementas este patrón en tus proyectos o manejas tus secretos de otra forma? Comparte tu experiencia en los comentarios.
