Variables de entorno

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

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

Cargando variables de entorno

Next.js tiene soporte integrado para cargar variables de entorno desde .env.local hacia 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 de 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,
  })
  // ...
}

Referenciando 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.

Nota importante: Si necesitas usar un carácter $ en el valor real de la variable, debes escaparlo con \, por ejemplo: \$.

Empaquetando variables de entorno para el navegador

Las variables de entorno que no tengan el prefijo NEXT_PUBLIC_ solo están disponibles en el entorno de Node.js, lo que significa que no son accesibles desde 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 "incluir" 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 necesitas prefijar la variable con NEXT_PUBLIC_. Por ejemplo:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

Esto le indicará a Next.js que reemplace todas las referencias a process.env.NEXT_PUBLIC_ANALYTICS_ID en el entorno de Node.js con el valor del entorno en el que ejecutes next build, permitiéndote usarlo en cualquier parte de tu código. Se incluirá 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 un pipeline de Heroku para promover builds de 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 construya el proyecto. Si necesitas acceder a valores de entorno en tiempo de ejecución, deberás 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í al tener 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>Hello World</h1>
}

export default HomePage

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

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

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

Variables de entorno por defecto

En general, solo se necesita un archivo .env.local. Sin embargo, a veces podrías querer añadir 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.

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

Variables de entorno en Vercel

Cuando despliegues tu aplicación Next.js en Vercel, las Variables de Entorno pueden configurarse en la configuración del proyecto.

Allí deberían configurarse todos los tipos de Variables de Entorno. 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

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 necesitarás hacer esto manualmente ya que las herramientas de prueba se encargarán de ello.

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 se espera que las pruebas produzcan los mismos resultados para todos. De esta manera, cada ejecución de pruebas usará los mismos valores por defecto en diferentes ejecuciones ignorando tu .env.local (que está destinado a sobrescribir el conjunto por defecto).

Nota importante: Al igual que con las Variables de Entorno por Defecto, el archivo .env.test debe incluirse en tu repositorio, pero .env.test.local no debería, ya que los archivos .env*.local están destinados a ser ignorados mediante .gitignore.

Mientras ejecutas pruebas unitarias, puedes asegurarte de cargar tus variables de entorno de la misma manera que lo hace Next.js utilizando 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.

Nota importante: Los valores permitidos para NODE_ENV son production, development y test.

Notas importantes

• 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 automáticamente asignará development cuando ejecutes el comando next dev, o production para todos los demás comandos.