Variables de entorno

Next.js incluye soporte integrado para variables de entorno, lo que te permite:

• Usar .env.local para cargar variables de entorno
• Incluir variables de entorno para el navegador prefijándolas con NEXT_PUBLIC_

Carga de Variables de Entorno

Next.js tiene soporte integrado para cargar variables de entorno desde .env.local a process.env.

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

Esto carga process.env.DB_HOST, process.env.DB_USER y process.env.DB_PASS en el entorno Node.js automáticamente, permitiéndote usarlos en métodos de obtención de datos de Next.js y rutas API.

Por ejemplo, usando getStaticProps:

export async function getStaticProps() {
  const db = await myDB.connect({
    host: process.env.DB_HOST,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
  })
  // ...
}

Referencia a Otras Variables

Next.js expandirá automáticamente variables que usen $ para referenciar otras variables, como $VARIABLE dentro de tus archivos .env*. Esto te permite referenciar otros secretos. Por ejemplo:

TWITTER_USER=nextjs
TWITTER_URL=https://twitter.com/$TWITTER_USER

En el ejemplo anterior, process.env.TWITTER_URL se establecería como https://twitter.com/nextjs.

Bueno saber: Si necesitas usar un carácter $ en el valor real, debe escaparse como \$.

Incluir Variables de Entorno para el Navegador

Las variables de entorno que no tengan el prefijo NEXT_PUBLIC_ solo están disponibles en el entorno Node.js, lo que significa que no son accesibles para el navegador (el cliente se ejecuta en un entorno diferente).

Para hacer que el valor de una variable de entorno sea accesible en el navegador, Next.js puede "insertar" un valor, en tiempo de compilación, en el paquete js que se entrega al cliente, reemplazando todas las referencias a process.env.[variable] con un valor estático. Para indicarle que haga esto, solo tienes que prefijar la variable con NEXT_PUBLIC_. Por ejemplo:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

Esto le dirá a Next.js que reemplace todas las referencias a process.env.NEXT_PUBLIC_ANALYTICS_ID en el entorno Node.js con el valor del entorno en el que ejecutes next build, permitiéndote usarlo en cualquier parte de tu código. Se insertará en cualquier JavaScript enviado al navegador.

Nota: Después de la compilación, tu aplicación ya no responderá a cambios en estas variables de entorno. Por ejemplo, si usas una tubería de Heroku para promocionar slugs compilados en un entorno a otro, o si compilas y despliegas una única imagen Docker en múltiples entornos, todas las variables NEXT_PUBLIC_ se congelarán con el valor evaluado en tiempo de compilación, por lo que estos valores deben establecerse apropiadamente cuando se compile el proyecto. Si necesitas acceder a valores de entorno en tiempo de ejecución, tendrás que configurar tu propia API para proporcionarlos al cliente (ya sea bajo demanda o durante la inicialización).

import setupAnalyticsService from '../lib/my-analytics-service'

// 'NEXT_PUBLIC_ANALYTICS_ID' puede usarse aquí porque tiene el prefijo 'NEXT_PUBLIC_'.
// Se transformará en tiempo de compilación a `setupAnalyticsService('abcdefghijk')`.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hola Mundo</h1>
}

export default HomePage

Ten en cuenta que las búsquedas dinámicas no se insertarán, como:

// Esto NO se insertará, porque usa una variable
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])

// Esto NO se insertará, porque usa una variable
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

Variables de Entorno en Tiempo de Ejecución

Next.js puede soportar tanto variables de entorno en tiempo de compilación como en tiempo de ejecución.

Por defecto, las variables de entorno solo están disponibles en el servidor. Para exponer una variable de entorno al navegador, debe tener el prefijo NEXT_PUBLIC_. Sin embargo, estas variables públicas se insertarán en el paquete JavaScript durante next build.

Para leer variables de entorno en tiempo de ejecución, recomendamos usar getServerSideProps o adoptar incrementalmente el Enrutador de Aplicaciones. Con el Enrutador de Aplicaciones, podemos leer variables de entorno en el servidor de forma segura durante el renderizado dinámico. Esto te permite usar una única imagen Docker que puede promocionarse a través de múltiples entornos con diferentes valores.

import { unstable_noStore as noStore } from 'next/cache'

export default function Component() {
  noStore()
  // cookies(), headers(), y otras funciones dinámicas
  // también optarán por el renderizado dinámico, lo que significa
  // que esta variable de entorno se evalúa en tiempo de ejecución
  const value = process.env.MY_VALUE
  // ...
}

Bueno saber:

• Puedes ejecutar código al iniciar el servidor usando la función register.
• No recomendamos usar la opción runtimeConfig, ya que no funciona con el modo de salida independiente. En su lugar, recomendamos adoptar incrementalmente el Enrutador de Aplicaciones.

Variables de Entorno por Defecto

En general, solo se necesita un archivo .env.local. Sin embargo, a veces podrías querer añadir algunos valores por defecto para el entorno de development (next dev) o production (next start).

Next.js te permite establecer valores por defecto en .env (todos los entornos), .env.development (entorno de desarrollo) y .env.production (entorno de producción).

.env.local siempre sobrescribe los valores por defecto establecidos.

Bueno saber: Los archivos .env, .env.development y .env.production deben incluirse en tu repositorio ya que definen valores por defecto. .env*.local debe añadirse a .gitignore, ya que estos archivos están destinados a ignorarse. .env.local es donde se pueden almacenar secretos.

Variables de Entorno en Vercel

Al desplegar tu aplicación Next.js en Vercel, las Variables de Entorno pueden configurarse en la Configuración del Proyecto.

Todos los tipos de Variables de Entorno deben configurarse allí. Incluso las Variables de Entorno usadas en Desarrollo, que pueden descargarse a tu dispositivo local posteriormente.

Si has configurado Variables de Entorno de Desarrollo, puedes extraerlas a un .env.local para usarlas en tu máquina local con el siguiente comando:

vercel env pull .env.local

Bueno saber: Al desplegar tu aplicación Next.js en Vercel, tus variables de entorno en archivos .env* no estarán disponibles para Edge Runtime, a menos que sus nombres tengan el prefijo NEXT_PUBLIC_. Recomendamos encarecidamente gestionar tus variables de entorno en la Configuración del Proyecto, desde donde todas las variables de entorno están disponibles.

Variables de Entorno de Prueba

Además de los entornos development y production, hay una tercera opción disponible: test. De la misma manera que puedes establecer valores por defecto para entornos de desarrollo o producción, puedes hacer lo mismo con un archivo .env.test para el entorno de testing (aunque este no es tan común como los dos anteriores). Next.js no cargará variables de entorno desde .env.development o .env.production en el entorno de testing.

Esto es útil cuando ejecutas pruebas con herramientas como jest o cypress donde necesitas establecer variables de entorno específicas solo para propósitos de prueba. Los valores por defecto de prueba se cargarán si NODE_ENV está establecido como test, aunque normalmente no necesitas hacer esto manualmente ya que las herramientas de prueba lo manejarán por ti.

Hay una pequeña diferencia entre el entorno test, y los entornos development y production que debes tener en cuenta: .env.local no se cargará, ya que esperas que las pruebas produzcan los mismos resultados para todos. De esta manera, cada ejecución de prueba usará los mismos valores por defecto en diferentes ejecuciones ignorando tu .env.local (que está destinado a sobrescribir el conjunto por defecto).

Bueno saber: similar a las Variables de Entorno por Defecto, el archivo .env.test debe incluirse en tu repositorio, pero .env.test.local no, ya que .env*.local están destinados a ignorarse a través de .gitignore.

Mientras ejecutas pruebas unitarias, puedes asegurarte de cargar tus variables de entorno de la misma manera que lo hace Next.js aprovechando la función loadEnvConfig del paquete @next/env.

// Lo siguiente puede usarse en un archivo de configuración global de Jest o similar para tu configuración de pruebas
import { loadEnvConfig } from '@next/env'

export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

Orden de Carga de Variables de Entorno

Las variables de entorno se buscan en los siguientes lugares, en orden, deteniéndose una vez que se encuentra la variable.

1. process.env
2. .env.$(NODE_ENV).local
3. .env.local (No se comprueba cuando NODE_ENV es test.)
4. .env.$(NODE_ENV)
5. .env

Por ejemplo, si NODE_ENV es development y defines una variable tanto en .env.development.local como en .env, se usará el valor en .env.development.local.

Bueno saber: Los valores permitidos para NODE_ENV son production, development y test.

Bueno saber

• Si estás usando un directorio /src, los archivos .env.* deben permanecer en la raíz de tu proyecto.
• Si la variable de entorno NODE_ENV no está asignada, Next.js la asigna automáticamente a development cuando ejecutas el comando next dev, o a production para todos los demás comandos.

Historial de Versiones