Entender cómo Next.js maneja las variables de entorno es fundamental para evitar problemas de debugging y proteger información sensible. A diferencia de otros frameworks, Next.js carga automáticamente el archivo .env.local y aplica una distinción crucial entre las variables disponibles en el servidor y las que llegan al navegador.
¿Por qué Next.js diferencia entre variables del servidor y del cliente?
Next.js incorpora una capa adicional de seguridad que evita que, sin darnos cuenta, expongamos información sensible al navegador. Por defecto, cualquier variable definida en .env.local solo está disponible en el servidor, es decir, dentro de funciones como getStaticProps o en las páginas de API de Next.js.
Esto significa que si definimos una variable como SPACE_ID y la intentamos leer desde un componente de React que se renderiza en el cliente, el valor será undefined [02:05]. Esto no es un error: es un mecanismo de protección intencional.
¿Qué sucede cuando usamos el prefijo NEXT_PUBLIC?
Para que una variable de entorno esté disponible tanto en el servidor como en el navegador, debemos agregar el prefijo NEXT_PUBLIC_ al nombre de la variable. Por ejemplo:
SPACE_ID → solo disponible en el servidor.NEXT_PUBLIC_SPACE_ID → disponible en servidor y navegador.
Cuando se utiliza este prefijo, Next.js se asegura de inyectar el valor en el bundle del cliente. Al ver NEXT_PUBLIC_ en el nombre, nuestro cerebro se activa de inmediato para recordar que ese valor será público y cualquier persona podría verlo desde el navegador [04:15].
¿Cómo se comporta en la práctica?
Durante la exploración en código, se realizaron varias pruebas que ilustran este comportamiento:
- Un
console.log de process.env.NEXT_PUBLIC_SPACE_ID dentro del componente de React mostró el valor correctamente en la consola del navegador [01:05].
- Al eliminar el prefijo
NEXT_PUBLIC_ y dejar solo SPACE_ID, el resultado fue undefined tanto en la consola del navegador como en la terminal del servidor cuando se ejecutó fuera de getStaticProps [02:05].
- Al mover el
console.log dentro de getStaticProps y usar NEXT_PUBLIC_SPACE_ID, el valor apareció correctamente en la terminal del servidor, pero no en la consola del navegador, porque la ejecución ocurrió del lado del servidor [03:10].
- Al colocar el
console.log en un componente que se renderiza del lado del cliente (Client Side Rendering), el valor con prefijo NEXT_PUBLIC_ se mostró de inmediato [03:55].
¿Cuándo usar NEXT_PUBLIC y cuándo no?
La decisión depende de la naturaleza de la información:
- Sin prefijo: claves secretas de API, contraseñas de bases de datos, tokens privados. Todo lo que debe permanecer exclusivamente en el servidor.
- Con prefijo
NEXT_PUBLIC_: tokens de acceso público, identificadores de recursos que no comprometen la seguridad aunque sean visibles.
En el contexto del curso, se utiliza NEXT_PUBLIC_ porque los tokens de acceso empleados corresponden a recursos públicos y es relativamente seguro compartirlos en el navegador [05:08].
¿Cómo carga Next.js el archivo .env.local?
Una de las ventajas de Next.js es que carga automáticamente el archivo .env.local sin necesidad de configurar librerías adicionales como dotenv. Basta con crear el archivo en la raíz del proyecto y definir las variables con el formato NOMBRE=valor. Next.js las leerá al iniciar el servidor y las pondrá disponibles a través de process.env [00:10].
Tener clara esta distinción entre variables públicas y privadas te ahorrará muchos dolores de cabeza al momento de hacer debugging. Si alguna variable aparece como undefined en el navegador, lo primero que debes verificar es si lleva el prefijo NEXT_PUBLIC_. ¿Has tenido algún problema similar con variables de entorno? Comparte tu experiencia en los comentarios.
