dotenv

Dotenv es un módulo sin dependencias que carga variables de entorno desde un archivo .env en process.env. Guardar la configuración en el entorno, separada del código, se basa en la metodología de The Twelve-Factor App.

Ver el tutorial

 

Uso

Instálalo.

npm install dotenv --save

Crea un archivo .env en la raíz de tu proyecto:

# .env
S3_BUCKET="YOURS3BUCKET"
SECRET_KEY="YOURSECRETKEYGOESHERE"

Y lo antes posible en tu aplicación, importa y configura dotenv:

// index.js
require('dotenv').config() // o import 'dotenv/config' si usas ES6
...
console.log(process.env) // elimínalo después de confirmar que funciona

$ node index.js
◇ injected env (14) from .env

Eso es todo. process.env ahora tiene las claves y valores que definiste en tu archivo .env.

 

Uso con agentes

Instala este repositorio como paquete de habilidad para tu agente:

npx skills add motdotla/dotenv

# luego dile a Claude/Codex cosas como:
configura dotenv
actualiza dotenv a dotenvx

 

Avanzado

ES6

Importa con ES6:

import 'dotenv/config'

Import con ES6 si necesitas establecer opciones de configuración:

import dotenv from 'dotenv'
dotenv.config({ path: '/custom/path/to/.env' })

bun

bun add dotenv

yarn

yarn add dotenv

pnpm

pnpm add dotenv

Monorepos

Para monorepos con una estructura como apps/backend/app.js, coloca el archivo .env en la raíz de la carpeta donde corre tu proceso app.js.

# app/backend/.env
S3_BUCKET="YOURS3BUCKET"
SECRET_KEY="YOURSECRETKEYGOESHERE"

Valores Multilínea

Si necesitas variables multilínea, por ejemplo claves privadas, ya son compatibles (>= v15.0.0) con saltos de línea:

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END RSA PRIVATE KEY-----"

Como alternativa, puedes usar comillas dobles y el carácter \n:

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END RSA PRIVATE KEY-----\n"

Comentarios

Puedes agregar comentarios en su propia línea o al final de una línea:

# Este es un comentario
SECRET_KEY=YOURSECRETKEYGOESHERE # comentario
SECRET_HASH="something-with-a-#-hash"

Los comentarios empiezan donde aparece #, así que si tu valor contiene # debes envolverlo entre comillas. Este es un cambio incompatible desde >= v15.0.0.

Análisis

El motor que analiza el contenido del archivo de variables de entorno está disponible para su uso. Acepta un String o Buffer y devuelve un objeto con las claves y valores analizados.

const dotenv = require('dotenv')
const buf = Buffer.from('BASIC=basic')
const config = dotenv.parse(buf) // devolverá un objeto
console.log(typeof config, config) // objeto { BASIC : 'basic' }

Precarga

Nota: considera usar dotenvx en lugar de precargar. Ahora lo hago (y lo recomiendo).

Cumple el mismo propósito (no necesitas hacer require y cargar dotenv), agrega mejor depuración y funciona con CUALQUIER lenguaje, framework o plataforma. – motdotla

Puedes usar la opción de línea de comandos --require (-r) para precargar dotenv. Con esto no necesitas requerir ni cargar dotenv en el código de tu aplicación.

$ node -r dotenv/config your_script.js

Las opciones de configuración de abajo se aceptan como argumentos de línea de comandos en el formato dotenv_config_<option>=value

$ node -r dotenv/config your_script.js dotenv_config_path=/custom/path/to/.env dotenv_config_debug=true

Además, puedes usar variables de entorno para establecer opciones de configuración. Los argumentos de línea de comandos tienen prioridad.

$ DOTENV_CONFIG_<OPTION>=value node -r dotenv/config your_script.js

$ DOTENV_CONFIG_ENCODING=latin1 DOTENV_CONFIG_DEBUG=true node -r dotenv/config your_script.js dotenv_config_path=/custom/path/to/.env

Expansión de Variables

Usa dotenvx para expansión de variables.

Referencia y expande variables que ya existen en tu máquina para usarlas en tu archivo .env.

# .env
USERNAME="username"
DATABASE_URL="postgres://${USERNAME}@localhost/my_database"

// index.js
console.log('DATABASE_URL', process.env.DATABASE_URL)

$ dotenvx run --debug -- node index.js
⟐ injected env (2) from .env · dotenvx@1.59.1
DATABASE_URL postgres://username@localhost/my_database

Sustitución de Comandos

Usa dotenvx para sustitución de comandos.

Agrega la salida de un comando a una de tus variables en tu archivo .env.

# .env
DATABASE_URL="postgres://$(whoami)@localhost/my_database"

// index.js
console.log('DATABASE_URL', process.env.DATABASE_URL)

$ dotenvx run --debug -- node index.js
⟐ injected env (1) from .env · dotenvx@1.59.1
DATABASE_URL postgres://yourusername@localhost/my_database

Cifrado

Usa dotenvx para cifrado.

Agrega cifrado a tus archivos .env con un solo comando.

$ dotenvx set HELLO Production -f .env.production
$ echo "console.log('Hello ' + process.env.HELLO)" > index.js

$ DOTENV_PRIVATE_KEY_PRODUCTION="<.env.production private key>" dotenvx run -- node index.js
⟐ injected env (2) from .env.production · dotenvx@1.59.1
Hello Production

más información

Múltiples Entornos

Usa dotenvx para administrar múltiples entornos.

Ejecuta cualquier entorno localmente. Crea un archivo .env.ENVIRONMENT y usa -f para cargarlo. Es simple y flexible.

$ echo "HELLO=production" > .env.production
$ echo "console.log('Hello ' + process.env.HELLO)" > index.js

$ dotenvx run -f=.env.production -- node index.js
Hello production
> ^^

o con múltiples archivos .env

$ echo "HELLO=local" > .env.local
$ echo "HELLO=World" > .env
$ echo "console.log('Hello ' + process.env.HELLO)" > index.js

$ dotenvx run -f=.env.local -f=.env -- node index.js
Hello local

más ejemplos de entornos

Producción

Usa dotenvx para despliegues en producción.

Crea un archivo .env.production.

$ echo "HELLO=production" > .env.production

Cífralo.

$ dotenvx encrypt -f .env.production

Configura DOTENV_PRIVATE_KEY_PRODUCTION (está en .env.keys) en tu servidor.

$ heroku config:set DOTENV_PRIVATE_KEY_PRODUCTION=value

Haz commit de tu archivo .env.production y despliega.

$ git add .env.production
$ git commit -m "encrypted .env.production"
$ git push heroku main

Dotenvx descifrará e inyectará los secretos en runtime usando dotenvx run -- node index.js.

Sincronización

Usa dotenvx para sincronizar tus archivos .env.

Cífralos con dotenvx encrypt -f .env e inclúyelos de forma segura en el control de código fuente. Tus secretos se sincronizan de forma segura con git.

Esto sigue las reglas de Twelve-Factor App al generar una clave de descifrado separada del código.

Más Ejemplos

Mira ejemplos de uso de dotenv con distintos frameworks, lenguajes y configuraciones.

• nodejs
• nodejs (debug on)
• nodejs (override on)
• nodejs (processEnv override)
• esm
• esm (preload)
• typescript
• typescript parse
• typescript config
• webpack
• webpack (plugin)
• react
• react (typescript)
• express
• nestjs
• fastify

 

Preguntas Frecuentes

¿Debo hacer commit de mi archivo .env?

No.

A menos que lo cifres con dotenvx. En ese caso sí lo recomendamos.

¿Qué pasa con la expansión de variables?

Usa dotenvx.

¿Debo tener múltiples archivos .env?

Recomendamos crear un archivo .env por entorno. Usa .env para local/desarrollo, .env.production para producción, etc. Esto sigue los principios de Twelve-Factor porque cada uno pertenece de forma independiente a su entorno. Evita configuraciones personalizadas con herencia (.env.production hereda valores de .env, por ejemplo). Es mejor duplicar valores cuando sea necesario en cada archivo .env.environment.

En una app twelve-factor, las variables de entorno son controles granulares, totalmente ortogonales entre sí. Nunca se agrupan como “entornos”; en cambio, se administran de forma independiente por despliegue. Este modelo escala de forma natural a medida que la app crece en más despliegues a lo largo del tiempo.

– The Twelve-Factor App

Además, recomendamos usar dotenvx para cifrarlos y administrarlos.

¿Cómo uso dotenv con import?

Simplemente..

// index.mjs (ESM)
import 'dotenv/config' // ver https://github.com/motdotla/dotenv#como-uso-dotenv-con-import
import express from 'express'

Un poco de contexto..

Cuando ejecutas un módulo que contiene una declaración import, primero se cargan los módulos importados y luego se ejecuta cada cuerpo de módulo en un recorrido en profundidad del grafo de dependencias, evitando ciclos al omitir lo que ya se ejecutó.

– ES6 In Depth: Modules

¿Qué significa esto en lenguaje simple? Que parece que lo siguiente debería funcionar, pero no funciona.

errorReporter.mjs:

class Client {
  constructor (apiKey) {
    console.log('apiKey', apiKey)

    this.apiKey = apiKey
  }
}

export default new Client(process.env.API_KEY)

index.mjs:

// Nota: esto es INCORRECTO y no funcionará
import * as dotenv from 'dotenv'
dotenv.config()

import errorReporter from './errorReporter.mjs' // process.env.API_KEY estará vacío

process.env.API_KEY estará vacío.

En su lugar, index.mjs debería escribirse así..

import 'dotenv/config'

import errorReporter from './errorReporter.mjs'

¿Tiene sentido? Es un poco poco intuitivo, pero así funciona la importación de módulos ES6. Aquí tienes un ejemplo funcional de este problema.

Hay dos alternativas a este enfoque:

1. Precargar con dotenvx: dotenvx run -- node index.js (Nota: con este enfoque no necesitas import dotenv)
2. Crear un archivo separado que ejecute config primero, como se indica en este comentario de #133

¿Puedo personalizar/escribir plugins para dotenv?

Sí. dotenv.config() devuelve un objeto que representa el archivo .env analizado. Con eso tienes lo necesario para seguir estableciendo valores en process.env. Por ejemplo:

```js const dotenv = require('dotenv') const variableExpansion = require('dotenv-expand') const myEnv = dotenv.conf