Files

2026-04-12 09:16:09 +00:00

24 KiB

Raw Blame History

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.

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:

Precargar con dotenvx: dotenvx run -- node index.js (Nota: con este enfoque no necesitas import dotenv)
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:

const dotenv = require('dotenv')
const variableExpansion = require('dotenv-expand')
const myEnv = dotenv.config()
variableExpansion(myEnv)

¿Qué reglas sigue el motor de análisis?

El motor de análisis actualmente soporta las siguientes reglas:

BASIC=basic se convierte en {BASIC: 'basic'}
las líneas vacías se omiten
las líneas que empiezan con # se tratan como comentarios
# marca el inicio de un comentario (a menos que el valor esté entre comillas)
los valores vacíos se convierten en cadenas vacías (EMPTY= pasa a {EMPTY: ''})
las comillas internas se conservan (piensa en JSON) (JSON={"foo": "bar"} se convierte en {JSON:"{\"foo\": \"bar\"}")
se elimina el espacio al principio y al final de valores sin comillas (más en trim) (FOO= some value pasa a {FOO: 'some value'})
los valores con comillas simples o dobles se escapan (SINGLE_QUOTE='quoted' pasa a {SINGLE_QUOTE: "quoted"})
los valores entre comillas simples o dobles mantienen los espacios en ambos extremos (FOO=" some value " pasa a {FOO: ' some value '})
los valores entre comillas dobles expanden saltos de línea (MULTILINE="new\nline" pasa a

{MULTILINE: 'new
line'}

se admiten backticks (BACKTICK_KEY=`This has 'single' and "double" quotes inside of it.`)

¿Qué hay de sincronizar y proteger archivos .env?

Usa dotenvx para habilitar la sincronización de archivos .env cifrados sobre git.

¿Qué pasa si hago commit accidentalmente de mi archivo `.env`?

Elimínalo, borra el historial de git y luego instala el hook de pre-commit de git para evitar que vuelva a pasar.

npm i -g @dotenvx/dotenvx
dotenvx precommit --install

¿Qué pasa con variables de entorno que ya estaban definidas?

Por defecto, nunca modificamos variables de entorno que ya estén definidas. En particular, si hay una variable en tu archivo .env que colisiona con una ya existente en tu entorno, esa variable se omite.

Si en cambio quieres sobrescribir process.env, usa la opción override.

require('dotenv').config({ override: true })

¿Cómo evito incluir mi archivo `.env` en un build de Docker?

Usa el hook de prebuild para docker.

# Dockerfile
...
RUN curl -fsS https://dotenvx.sh/ | sh
...
RUN dotenvx prebuild
CMD ["dotenvx", "run", "--", "node", "index.js"]

¿Por qué no aparecen mis variables de entorno en React?

Tu código React corre en Webpack, donde el módulo fs o incluso el global process no son accesibles de forma predeterminada. process.env solo se puede inyectar mediante configuración de Webpack.

Si usas react-scripts, distribuido vía create-react-app, ya incluye dotenv, pero con una condición. Antepone REACT_APP_ a tus variables de entorno. Mira este stack overflow para más detalles.

Si usas otros frameworks (por ejemplo, Next.js, Gatsby...), debes revisar su documentación para inyectar variables de entorno en el cliente.

¿Por qué el archivo `.env` no carga mis variables de entorno correctamente?

Lo más probable es que tu archivo .env no esté en el lugar correcto. Mira este stack overflow.

Activa el modo debug y prueba de nuevo..

require('dotenv').config({ debug: true })

Recibirás un error útil en la consola.

¿Por qué recibo el error `Module not found: Error: Can't resolve 'crypto|os|path'`?

Estás usando dotenv en el front-end y no incluiste un polyfill. Webpack < 5 solía incluirlos. Haz lo siguiente:

npm install node-polyfill-webpack-plugin

Configura tu webpack.config.js con algo como lo siguiente.

require('dotenv').config()

const path = require('path');
const webpack = require('webpack')

const NodePolyfillPlugin = require('node-polyfill-webpack-plugin')

module.exports = {
  mode: 'development',
  entry: './src/index.ts',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  plugins: [
    new NodePolyfillPlugin(),
    new webpack.DefinePlugin({
      'process.env': {
        HELLO: JSON.stringify(process.env.HELLO)
      }
    }),
  ]
};

Como alternativa, usa dotenv-webpack, que hace esto y más por detrás.

Documentación

Dotenv expone tres funciones:

config
parse
populate

Config

config leerá tu archivo .env, analizará su contenido, lo asignará a process.env, y devolverá un objeto con una clave parsed con el contenido cargado o una clave error si falla.

const result = dotenv.config()

if (result.error) {
  throw result.error
}

console.log(result.parsed)

También puedes pasar opciones a config.

Opciones

path

Por defecto: path.resolve(process.cwd(), '.env')

Especifica una ruta personalizada si tu archivo de variables de entorno está en otro lugar.

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

Por defecto, config buscará un archivo llamado .env en el directorio de trabajo actual.

Pasa múltiples archivos como un arreglo; se analizarán en orden y se combinarán con process.env (o option.processEnv, si se define). El primer valor asignado a una variable prevalece, salvo que options.override esté activo; en ese caso prevalece el último. Si un valor ya existe en process.env y options.override NO está activo, no se hará ningún cambio en ese valor.

require('dotenv').config({ path: ['.env.local', '.env'] })

quiet

Por defecto: false

Suprime el mensaje de logging en tiempo de ejecución.

// index.js
require('dotenv').config({ quiet: false }) // cambia a true para suprimir
console.log(`Hello ${process.env.HELLO}`)

# .env
HELLO=World

$ node index.js
Hola Mundo

encoding

Por defecto: utf8

Especifica la codificación del archivo que contiene variables de entorno.

require('dotenv').config({ encoding: 'latin1' })

debug

Por defecto: false

Activa logs para depurar por qué ciertas claves o valores no se establecen como esperas.

require('dotenv').config({ debug: process.env.DEBUG })

override

Por defecto: false

Sobrescribe cualquier variable de entorno ya definida en tu máquina con valores de tus archivos .env. Si se proporcionan múltiples archivos en option.path, override también aplica al combinar cada archivo con el siguiente. Sin override, prevalece el primer valor. Con override, prevalece el último.

require('dotenv').config({ override: true })

processEnv

Por defecto: process.env

Especifica un objeto donde escribir tus variables de entorno. Por defecto usa process.env.

const myObject = {}
require('dotenv').config({ processEnv: myObject })

console.log(myObject) // valores desde .env
console.log(process.env) // esto no se modificó ni escribió

Parse

El motor que analiza el contenido de tu archivo de variables de entorno está disponible para usar. 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' }

Opciones

debug

Por defecto: false

Activa logs para depurar por qué ciertas claves o valores no se establecen como esperas.

const dotenv = require('dotenv')
const buf = Buffer.from('hola mundo')
const opt = { debug: true }
const config = dotenv.parse(buf, opt)
// espera un mensaje de depuración porque el buffer no tiene formato KEY=VAL

Populate

El motor que carga el contenido de tu archivo .env en process.env está disponible para su uso. Acepta un objetivo, una fuente y opciones. Es útil para usuarios avanzados que quieren proveer sus propios objetos.

Por ejemplo, personalizando la fuente:

const dotenv = require('dotenv')
const parsed = { HELLO: 'world' }

dotenv.populate(process.env, parsed)

console.log(process.env.HELLO) // world

Por ejemplo, personalizando la fuente Y el objetivo:

const dotenv = require('dotenv')
const parsed = { HELLO: 'universe' }
const target = { HELLO: 'world' } // objeto inicial

dotenv.populate(target, parsed, { override: true, debug: true })

console.log(target) // { HELLO: 'universe' }

opciones

Debug

Por defecto: false

Activa logs para depurar por qué ciertas claves o valores no se están cargando como esperas.

override

Por defecto: false

Sobrescribe cualquier variable de entorno que ya haya sido definida.

CHANGELOG

Ver CHANGELOG.md

¿Quién usa dotenv?

Estos módulos de npm dependen de él.

Los proyectos que lo extienden suelen usar la palabra clave "dotenv" en npm.

24 KiB Raw Blame History Unescape Escape

dotenv

Uso

Uso con agentes

Avanzado

Preguntas Frecuentes

Documentación

Config

Opciones

path

quiet

encoding

debug

override

processEnv

Parse

Opciones

debug

Populate

opciones

Debug

override

CHANGELOG

¿Quién usa dotenv?

24 KiB

Raw Blame History