dotenv - npm Package Compare versions

Comparing version 16.1.0-rc1 to 16.1.0-rc2

CHANGELOG.md

@@ -7,6 +7,8 @@ # Changelog
 
-## [16.1.0](https://github.com/motdotla/dotenv/compare/v16.0.3...v16.1.0) (2023-04-01)
-
 ### Added
 
+- Add `populate` convenience method [#733](https://github.com/motdotla/dotenv/pull/733)
+- Remove "cannot resolve 'fs'" error on tools like Replit [#693](https://github.com/motdotla/dotenv/pull/693)
+- Accept URL as path option [#720](https://github.com/motdotla/dotenv/pull/720)
+- Spanish language README [#698](https://github.com/motdotla/dotenv/pull/698)
 - Add `.env.vault` support. 🎉 ([#730](https://github.com/motdotla/dotenv/pull/730))
@@ -13,0 +15,0 @@

lib/main.d.ts

@@ -29,3 +29,3 @@ // TypeScript Version: 3.0
    */
-  path?: string;
+  path?: string | URL;
 
@@ -65,2 +65,30 @@ /**
 
+export interface DotenvPopulateOptions {
+  /**
+   * Default: `false`
+   *
+   * Turn on logging to help debug why certain keys or values are not being set as you expect.
+   *
+   * example: `require('dotenv').config({ debug: process.env.DEBUG })`
+   */
+  debug?: boolean;
+
+  /**
+   * Default: `false`
+   *
+   * Override any environment variables that have already been set on your machine with values from your .env file.
+   *
+   * example: `require('dotenv').config({ override: true })`
+   */
+  override?: boolean;
+}
+
+export interface DotenvPopulateOutput {
+  error?: Error;
+}
+
+export interface DotenvPopulateInput {
+  [name: string]: string;
+}
+
 /**
@@ -76,1 +104,14 @@ * Loads `.env` file contents into process.env.
 export function config(options?: DotenvConfigOptions): DotenvConfigOutput;
+
+/**
+ * Loads `source` json contents into `target` like process.env.
+ *
+ * See https://docs.dotenv.org
+ *
+ * @param target - the target JSON object
+ * @param source - the source JSON object
+ * @param options - additional options. example: `{ debug: true, override: false }`
+ * @returns {void}
+ *
+ */
+export function populate(target: DotenvPopulateInput, source: DotenvPopulateInput, options?: DotenvConfigOptions): DotenvPopulateOutput;

lib/main.js

@@ -11,3 +11,3 @@ const fs = require('fs')
 
-// Parser src into an Object
+// Parse src into an Object
 function parse (src) {
@@ -166,24 +166,4 @@ const obj = {}
 
-  const debug = Boolean(options && options.debug)
-  const override = Boolean(options && options.override)
+  DotenvModule.populate(process.env, parsed, options)
 
-  // Set process.env
-  for (const key of Object.keys(parsed)) {
-    if (Object.prototype.hasOwnProperty.call(process.env, key)) {
-      if (override === true) {
-        process.env[key] = parsed[key]
-      }
-
-      if (debug) {
-        if (override === true) {
-          _debug(`"${key}" is already defined in \`process.env\` and WAS overwritten`)
-        } else {
-          _debug(`"${key}" is already defined in \`process.env\` and was NOT overwritten`)
-        }
-      }
-    } else {
-      process.env[key] = parsed[key]
-    }
-  }
-
   return { parsed }
@@ -196,3 +176,2 @@ }
   const debug = Boolean(options && options.debug)
-  const override = Boolean(options && options.override)
 
@@ -210,22 +189,6 @@ if (options) {
     // Specifying an encoding returns a string instead of a buffer
-    const parsed = parse(fs.readFileSync(dotenvPath, { encoding }))
+    const parsed = DotenvModule.parse(fs.readFileSync(dotenvPath, { encoding }))
 
-    Object.keys(parsed).forEach(function (key) {
-      if (!Object.prototype.hasOwnProperty.call(process.env, key)) {
-        process.env[key] = parsed[key]
-      } else {
-        if (override === true) {
-          process.env[key] = parsed[key]
-        }
+    DotenvModule.populate(process.env, parsed, options)
 
-        if (debug) {
-          if (override === true) {
-            _debug(`"${key}" is already defined in \`process.env\` and WAS overwritten`)
-          } else {
-            _debug(`"${key}" is already defined in \`process.env\` and was NOT overwritten`)
-          }
-        }
-      }
-    })
-
     return { parsed }
@@ -291,2 +254,31 @@ } catch (e) {
 
+// Populate process.env with parsed values
+function populate (processEnv, parsed, options = {}) {
+  const debug = Boolean(options && options.debug)
+  const override = Boolean(options && options.override)
+
+  if (typeof parsed !== 'object') {
+    throw new Error('OBJECT_REQUIRED: Please check the processEnv argument being passed to populate')
+  }
+
+  // Set process.env
+  for (const key of Object.keys(parsed)) {
+    if (Object.prototype.hasOwnProperty.call(processEnv, key)) {
+      if (override === true) {
+        processEnv[key] = parsed[key]
+      }
+
+      if (debug) {
+        if (override === true) {
+          _debug(`"${key}" is already defined and WAS overwritten`)
+        } else {
+          _debug(`"${key}" is already defined and was NOT overwritten`)
+        }
+      }
+    } else {
+      processEnv[key] = parsed[key]
+    }
+  }
+}
+
 const DotenvModule = {
@@ -298,3 +290,4 @@ _configDotenv,
   decrypt,
-  parse
+  parse,
+  populate
 }
@@ -308,3 +301,4 @@
 module.exports.parse = DotenvModule.parse
+module.exports.populate = DotenvModule.populate
 
 module.exports = DotenvModule

package.json

 {
   "name": "dotenv",
-  "version": "16.1.0-rc1",
+  "version": "16.1.0-rc2",
   "description": "Loads environment variables from .env file",
@@ -9,4 +9,4 @@ "main": "lib/main.js",
     ".": {
+      "types": "./lib/main.d.ts",
       "require": "./lib/main.js",
-      "types": "./lib/main.d.ts",
       "default": "./lib/main.js"
@@ -47,13 +47,18 @@ },
   "devDependencies": {
-    "@types/node": "^17.0.9",
+    "@definitelytyped/dtslint": "^0.0.133",
+    "@types/node": "^18.11.3",
     "decache": "^4.6.1",
-    "dtslint": "^3.7.0",
-    "sinon": "^12.0.1",
-    "standard": "^16.0.4",
+    "sinon": "^14.0.1",
+    "standard": "^17.0.0",
     "standard-markdown": "^7.1.0",
-    "standard-version": "^9.3.2",
-    "tap": "^15.1.6",
+    "standard-version": "^9.5.0",
+    "tap": "^16.3.0",
     "tar": "^6.1.11",
-    "typescript": "^4.5.4"
+    "typescript": "^4.8.4"
   },
+  "browser": {
+    "fs": false,
+    "path": false,
+    "os": false
+  },
   "engines": {
@@ -60,0 +65,0 @@ "node": ">=12"

README.md

@@ -41,9 +41,6 @@ <div align="center">
 <hr>
-<br>
 </div>
 
-[![dotenv-vault](https://badge.dotenv.org/works-with.svg?r=1)](https://www.dotenv.org/r/github.com/dotenv-org/dotenv-vault?r=1) 
+# dotenv [![NPM version](https://img.shields.io/npm/v/dotenv.svg?style=flat-square)](https://www.npmjs.com/package/dotenv)
 
-# dotenv
-
 <img src="https://raw.githubusercontent.com/motdotla/dotenv/master/dotenv.svg" alt="dotenv" align="right" width="200" />
@@ -53,6 +50,6 @@
 
-[![NPM version](https://img.shields.io/npm/v/dotenv.svg?style=flat-square)](https://www.npmjs.com/package/dotenv)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
 [![Coverage Status](https://img.shields.io/coveralls/motdotla/dotenv/master.svg?style=flat-square)](https://coveralls.io/github/motdotla/dotenv?branch=coverall-intergration)
 [![LICENSE](https://img.shields.io/github/license/motdotla/dotenv.svg)](LICENSE)
+[![dotenv-vault](https://badge.dotenv.org/works-with.svg?r=1)](https://www.dotenv.org/r/github.com/dotenv-org/dotenv-vault?r=1) 
 
@@ -62,4 +59,5 @@ * [🌱 Install](#-install)
 * [🚀 Deploying (.env.vault) 🆕](#-deploying)
-* [🌴 Examples](#-examples)
-* [🦮 Docs](#-documentation)
+* [🌴 Multiple Environments 🆕](#-manage-multiple-environments)
+* [📚 Examples](#-examples)
+* [📖 Docs](#-documentation)
 * [❓ FAQ](#-faq)
@@ -70,2 +68,9 @@ * [⏱️ Changelog](./CHANGELOG.md)
 
+<a href="https://www.youtube.com/watch?v=YtkZR0NFd1g">
+<div align="right">
+<img src="https://img.youtube.com/vi/YtkZR0NFd1g/hqdefault.jpg" alt="how to use dotenv video tutorial" align="right" width="330" />
+<img src="https://simpleicons.vercel.app/youtube/ff0000" alt="youtube/@dotenvorg" align="right" width="24" />
+</div>
+</a>
+
 ```bash
@@ -94,8 +99,6 @@ # install locally (recommended)
 
-.. or using ES6?
+.. [or using ES6?](#how-do-i-use-dotenv-with-import)
 
 ```javascript
-import * as dotenv from 'dotenv' // see https://github.com/motdotla/dotenv#how-do-i-use-dotenv-with-import
-dotenv.config()
-import express from 'express'
+import 'dotenv/config'
 ```
@@ -188,63 +191,81 @@
 
-**Note: Unreleased. Coming April 17, 2023! Releasing as dotenv@16.1.0.**
+<a href="https://www.youtube.com/watch?v=Ad7Wl8iC3Rs">
+<div align="right">
+<img src="https://img.youtube.com/vi/Ad7Wl8iC3Rs/hqdefault.jpg" alt="how to deploy with a .env.vault file video tutorial" align="right" width="330" />
+<img src="https://simpleicons.vercel.app/youtube/ff0000" alt="youtube/@dotenvorg" align="right" width="24" />
+</div>
+</a>
 
-Up until recently (year 2023), we did not have an opinion on deploying your secrets to production. Dotenv had been focused on solving development secrets only. However, with the increasing number of secrets breaches like the [CircleCI breach](https://techcrunch.com/2023/01/05/circleci-breach/) we have formed an opinion.
+**Note: Currently released as RC Candidate [dotenv@16.1.0-rc1](https://www.npmjs.com/package/dotenv/v/16.1.0-rc1)**
 
-Don't scatter your secrets across multiple platforms and tools. Use a `.env.vault` file.
+Encrypt your environment variables by doing:
 
-The `.env.vault` file encrypts your secrets and decrypts them just-in-time on boot of your application. It uses a `DOTENV_KEY` environment variable that you set on your cloud platform or server. If there is a secrets breach, an attacker only gains access to your decryption key, not your secrets. They would additionally have to gain access to your codebase, find your .env.vault file, and decrypt it to get your secrets. This is much harder and more time consuming for an attacker.
+```shell
+npx dotenv-vault local build
+```
 
-It works in 3 easy steps.
+This will create an encrypted `.env.vault` file along with a `.env.keys` file containing the encryption keys. Set the `DOTENV_KEY` environment variable by copying and pasting the key value from the `.env.keys` file onto your server or cloud provider. For example in heroku:
 
-### 1. Create .env.ENVIRONMENT files
+```shell
+heroku config:set DOTENV_KEY=<key string from .env.keys>
+```
 
-In addition to your `.env` (development) file, create a `.env.ci`, `.env.staging`, and `.env.production` file.
+Commit your .env.vault file safely to code and deploy. Your .env.vault fill be decrypted on boot, its environment variables injected, and your app work as expected.
 
-(Have a custom environment? Just append it's name. For example, `.env.prod`.)
+## 🌴 Manage Multiple Environments
 
-Put your respective secrets in each of those files, just like you always have with your `.env` files. These files should NOT be committed to code.
+You have two options for managing multiple environments - locally managed or vault managed - both use <a href="https://github.com/dotenv-org/dotenv-vault">dotenv-vault</a>.
 
-### 2. Generate .env.vault file
+Locally managed never makes a remote API call. It is completely managed on your machine. Vault managed adds conveniences like backing up your .env file, secure sharing across your team, access permissions, and version history. Choose what works best for you.
 
-Run the build command to generate your `.env.vault` file.
+#### 💻 Locally Managed
 
+Create a `.env.production` file in the root of your project and put your production values there.
+
 ```
+# .env.production
+S3_BUCKET="PRODUCTION_S3BUCKET"
+SECRET_KEY="PRODUCTION_SECRETKEYGOESHERE"
+```
+
+Rebuild your `.env.vault` file.
+
+```
 $ npx dotenv-vault local build
 ```
 
-This command will read the contents of each of your `.env.*` files, encrypt them, and inject the encrypted versions into your `.env.vault` file. For example:
+Check your `.env.keys` file. There is a production `DOTENV_KEY` that coincides with the additional `DOTENV_VAULT_PRODUCTION` cipher in your `.env.vault` file.
 
+Set the production `DOTENV_KEY` on your server, recommit your `.env.vault` file to code, and deploy. That's it!
+
+#### 🔐 Vault Managed
+
+Sync your .env file. Run the push command and follow the instructions. [learn more](/docs/sync/quickstart)
+
 ```
-# .env.vault (generated with npx dotenv-vault local build)
-DOTENV_VAULT_DEVELOPMENT="X/GOMD7h/Fygjyq3+K2zbdyTBUBVA+mLivaSebqDMnLAencDGu9YvJji"
-DOTENV_VAULT_CI="SNnKvHTezcd0B8L+81lhcig+6GfkRxnlrgS1GG/2tJZ7KghOEJnM"
-DOTENV_VAULT_PRODUCTION="FudgivxdMrCKOKUeN+QieuCAoGiC2MstXL8JU6Pp4ILYu9wEwfqe4ne3e2jcVys="
-DOTENV_VAULT_STAGING="CZXrvrTusPLJlgm62uEppwCKZt6zEr4TGwlP8Z0McJd7I8KBF522JnhT9/8="
+$ npx dotenv-vault push
 ```
 
-Commit your `.env.vault` file safely to code. It SHOULD be committed to code.
+Manage multiple environments with the included UI. [learn more](/docs/tutorials/environments)
 
-### 3. Set DOTENV_KEY
+```
+$ npx dotenv-vault open
+```
 
-The build command also created a `.env.keys` file for you. This is where your `DOTENV_KEY` decryption keys live per environment.
+Build your `.env.vault` file with multiple environments.
 
 ```
-# DOTENV_KEYs (generated with npx dotenv-vault local build)
-DOTENV_KEY_DEVELOPMENT="dotenv://:key_[e-mail]/vault/.env.vault?environment=development"
-DOTENV_KEY_CI="dotenv://:key_[e-mail]/vault/.env.vault?environment=ci"
-DOTENV_KEY_STAGING="dotenv://:key_[e-mail]/vault/.env.vault?environment=staging"
+$ npx dotenv-vault build
 ```
 
-Go to your web server or cloud platform and set the environment variable `DOTENV_KEY` with the production value. For example, in heroku I'd run the following command.
+Access your `DOTENV_KEY`.
 
 ```
-heroku config:set DOTENV_KEY=dotenv://:key_[e-mail]/vault/.env.vault?environment=production
+$ npx dotenv-vault keys
 ```
 
-Then deploy your code. On boot, the `dotenv` library (>= 16.1.0) will see that a `DOTENV_KEY` is set and use its value to decrypt the production contents of the `.env.vault` file and inject them into your process.
+Set the production `DOTENV_KEY` on your server, recommit your `.env.vault` file to code, and deploy. That's it!
 
-No more scattered secrets across multiple platforms and tools.
+## 📚 Examples
 
-## 🌴 Examples
-
 See [examples](https://github.com/dotenv-org/examples) of using dotenv with various frameworks, languages, and configurations.
@@ -268,3 +289,3 @@
 
-## 🦮 Documentation
+## 📖 Documentation
 
@@ -451,4 +472,3 @@ Dotenv exposes two functions:
 // index.mjs (ESM)
-import * as dotenv from 'dotenv' // see https://github.com/motdotla/dotenv#how-do-i-use-dotenv-with-import
-dotenv.config()
+import 'dotenv/config' // see https://github.com/motdotla/dotenv#how-do-i-use-dotenv-with-import
 import express from 'express'
@@ -465,10 +485,12 @@ ```
 
+`errorReporter.mjs`:
 ```js
-// errorReporter.mjs
 import { Client } from 'best-error-reporting-service'
 
 export default new Client(process.env.API_KEY)
-
-// index.mjs
-import dotenv from 'dotenv'
+```
+`index.mjs`:
+```js
+// Note: this is INCORRECT and will not work
+import * as dotenv from 'dotenv'
 dotenv.config()
@@ -482,14 +504,7 @@
 
-Instead the above code should be written as..
+Instead, `index.mjs` should be written as..
 
 ```js
-// errorReporter.mjs
-import { Client } from 'best-error-reporting-service'
+import 'dotenv/config'
 
-export default new Client(process.env.API_KEY)
-
-// index.mjs
-import * as dotenv from 'dotenv'
-dotenv.config()
-
 import errorReporter from './errorReporter.mjs'
@@ -527,5 +542,1 @@ errorReporter.report(new Error('documented example'))
 Projects that expand it often use the [keyword "dotenv" on npm](https://www.npmjs.com/search?q=keywords:dotenv).
-
-[![Limited Edition Tee Original](https://img.shields.io/badge/Limited%20Edition%20Tee%20%F0%9F%91%95-Original-yellow?labelColor=black&style=plastic)](https://dotenv.gumroad.com/l/original)
-[![Limited Edition Tee Redacted](https://img.shields.io/badge/Limited%20Edition%20Tee%20%F0%9F%91%95-Redacted-gray?labelColor=black&style=plastic)](https://dotenv.gumroad.com/l/redacted)
-

Fixed alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

64837

increased by40.32%

Number of package files

11

increased by10%

Lines of code

371

increased by8.48%

Number of lines in readme file

532

increased by2.11%

Number of low supply chain risk alerts

6

decreased by-40%

No dependency changes