Cómo usar variables de entorno en Next.js

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

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

Advertencia: La plantilla predeterminada de create-next-app asegura que todos los archivos .env se añadan a tu .gitignore. Casi nunca querrás subir estos archivos a tu repositorio.

Cargar Variables de Entorno

Next.js tiene soporte integrado para cargar variables de entorno desde archivos .env* hacia process.env.

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

Nota: Next.js también soporta variables multilínea dentro de tus archivos .env*:

# .env

# puedes escribir con saltos de línea
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"

# o con `\n` dentro de comillas dobles
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----\n"

Nota: Si estás usando una carpeta /src, ten en cuenta que Next.js cargará los archivos .env solo desde la carpeta principal y no desde la carpeta /src. 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 usarlas en Route Handlers.

Por ejemplo:

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

Cargar Variables de Entorno con @next/env

Si necesitas cargar variables de entorno fuera del entorno de ejecución de Next.js, como en un archivo de configuración raíz para un ORM o un ejecutor de pruebas, puedes usar el paquete @next/env.

Este paquete se usa internamente por Next.js para cargar variables de entorno desde archivos .env*.

Para usarlo, instala el paquete y utiliza la función loadEnvConfig para cargar las variables de entorno:

npm install @next/env

import { loadEnvConfig } from '@next/env'

const projectDir = process.cwd()
loadEnvConfig(projectDir)

Luego, puedes importar la configuración donde sea necesario. Por ejemplo:

import './envConfig.ts'

export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
})

Referenciar Otras Variables

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

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

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

Bueno saber: Si necesitas usar una variable con un $ en el valor real, debe escaparse, ej. \$.

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 de 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 codificado. 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 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 insertará en cualquier JavaScript enviado al navegador.

Nota: Después de compilar, tu aplicación ya no responderá a cambios en estas variables de entorno. Por ejemplo, si usas un pipeline de Heroku para promocionar slugs compilados en un entorno a otro, o si compilas y despliegas una única imagen Docker a 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 el proyecto se compile. 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í ya que 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>Hello World</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.

Puedes leer de forma segura variables de entorno en el servidor durante el renderizado dinámico:

import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // cookies, headers y otras APIs 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
  // ...
}

Esto te permite usar una única imagen Docker que puede promocionarse a través de múltiples entornos con diferentes valores.

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 standalone. En su lugar, recomendamos adoptar incrementalmente el App Router si necesitas esta característica.

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 predeterminados 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 predeterminados 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 predeterminados de entorno en diferentes ejecuciones al ignorar tu .env.local (que está destinado a sobrescribir el conjunto predeterminado).

Bueno saber: similar a las Variables de Entorno Predeterminadas, 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 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 verifica 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 una carpeta /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 asigna development al ejecutar el comando next dev, o production para todos los demás comandos.

Historial de Versiones