Skip to content

Commit 155f0b5

Browse files
motdotlamotdotla
committed
Sort FAQ by summary length
1 parent 8c92230 commit 155f0b5

File tree

1 file changed

+109
-111
lines changed

1 file changed

+109
-111
lines changed

‎README.md‎

Lines changed: 109 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -534,17 +534,9 @@ Override any environment variables that have already been set.
534534
## FAQ
535535

536536
<details>
537-
<summary>Why is the `.env` file not loading my environment variables successfully?</summary>
538-
539-
Most likely your `.env` file is not in the correct place. [See this stack overflow](https://stackoverflow.com/questions/42335016/dotenv-file-is-not-loading-environment-variables).
540-
541-
Turn on debug mode and try again..
542-
543-
```js
544-
require('dotenv').config({ debug: true })
545-
```
537+
<summary>What about variable expansion?</summary>
546538

547-
You will receive a helpful error outputted to your console.
539+
Try [dotenv-expand](https://github.com/motdotla/dotenv-expand)
548540
</details>
549541

550542
<details>
@@ -556,6 +548,64 @@ passwords or API keys. Your production database should have a different
556548
password than your development database.
557549
</details>
558550

551+
<details>
552+
<summary>How do I use dotenv with `import`?</summary>
553+
554+
Simply..
555+
556+
```javascript
557+
// index.mjs (ESM)
558+
import 'dotenv/config' // see https://github.com/motdotla/dotenv#how-do-i-use-dotenv-with-import
559+
import express from 'express'
560+
```
561+
562+
A little background..
563+
564+
> When you run a module containing an `import` declaration, the modules it imports are loaded first, then each module body is executed in a depth-first traversal of the dependency graph, avoiding cycles by skipping anything already executed.
565+
>
566+
> – [ES6 In Depth: Modules](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/)
567+
568+
What does this mean in plain language? It means you would think the following would work but it won't.
569+
570+
`errorReporter.mjs`:
571+
```js
572+
class Client {
573+
constructor (apiKey) {
574+
console.log('apiKey', apiKey)
575+
576+
this.apiKey = apiKey
577+
}
578+
}
579+
580+
export default new Client(process.env.API_KEY)
581+
```
582+
`index.mjs`:
583+
```js
584+
// Note: this is INCORRECT and will not work
585+
import * as dotenv from 'dotenv'
586+
dotenv.config()
587+
588+
import errorReporter from './errorReporter.mjs' // process.env.API_KEY will be blank!
589+
```
590+
591+
`process.env.API_KEY` will be blank.
592+
593+
Instead, `index.mjs` should be written as..
594+
595+
```js
596+
import 'dotenv/config'
597+
598+
import errorReporter from './errorReporter.mjs'
599+
```
600+
601+
Does that make sense? It's a bit unintuitive, but it is how importing of ES6 modules work. Here is a [working example of this pitfall](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-es6-import-pitfall).
602+
603+
There are two alternatives to this approach:
604+
605+
1. Preload with dotenvx: `dotenvx run -- node index.js` (_Note: you do not need to `import` dotenv with this approach_)
606+
2. Create a separate file that will execute `config` first as outlined in [this comment on #133](https://github.com/motdotla/dotenv/issues/133#issuecomment-255298822)
607+
</details>
608+
559609
<details>
560610
<summary>Should I have multiple `.env` files?</summary>
561611

@@ -566,6 +616,19 @@ We recommend creating one `.env` file per environment. Use `.env` for local/deve
566616
> – [The Twelve-Factor App](http://12factor.net/config)
567617
</details>
568618
619+
<details>
620+
<summary>Can I customize/write plugins for dotenv?</summary>
621+
622+
Yes! `dotenv.config()` returns an object representing the parsed `.env` file. This gives you everything you need to continue setting values on `process.env`. For example:
623+
624+
```js
625+
const dotenv = require('dotenv')
626+
const variableExpansion = require('dotenv-expand')
627+
const myEnv = dotenv.config()
628+
variableExpansion(myEnv)
629+
```
630+
</details>
631+
569632
<details>
570633
<summary>What rules does the parsing engine follow?</summary>
571634

@@ -591,96 +654,71 @@ line'}
591654
</details>
592655

593656
<details>
594-
<summary>What happens to environment variables that were already set?</summary>
595-
596-
By default, we will never modify any environment variables that have already been set. In particular, if there is a variable in your `.env` file which collides with one that already exists in your environment, then that variable will be skipped.
597-
598-
If instead, you want to override `process.env` use the `override` option.
657+
<summary>What about syncing and securing .env files?</summary>
599658

600-
```javascript
601-
require('dotenv').config({ override: true })
602-
```
659+
Use [dotenvx](https://github.com/dotenvx/dotenvx) to unlock syncing encrypted .env files over git.
603660
</details>
604661

605662
<details>
606-
<summary>How come my environment variables are not showing up for React?</summary>
607-
608-
Your React code is run in Webpack, where the `fs` module or even the `process` global itself are not accessible out-of-the-box. `process.env` can only be injected through Webpack configuration.
663+
<summary>What if I accidentally commit my `.env` file to code?</summary>
609664

610-
If you are using [`react-scripts`](https://www.npmjs.com/package/react-scripts), which is distributed through [`create-react-app`](https://create-react-app.dev/), it has dotenv built in but with a quirk. Preface your environment variables with `REACT_APP_`. See [this stack overflow](https://stackoverflow.com/questions/42182577/is-it-possible-to-use-dotenv-in-a-react-project) for more details.
665+
Remove it, [remove git history](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository) and then install the [git pre-commit hook](https://github.com/dotenvx/dotenvx#pre-commit) to prevent this from ever happening again.
611666

612-
If you are using other frameworks (e.g. Next.js, Gatsby...), you need to consult their documentation for how to inject environment variables into the client.
667+
```
668+
brew install dotenvx/brew/dotenvx
669+
dotenvx precommit --install
670+
```
613671
</details>
614672

615673
<details>
616-
<summary>Can I customize/write plugins for dotenv?</summary>
674+
<summary>What happens to environment variables that were already set?</summary>
617675

618-
Yes! `dotenv.config()` returns an object representing the parsed `.env` file. This gives you everything you need to continue setting values on `process.env`. For example:
676+
By default, we will never modify any environment variables that have already been set. In particular, if there is a variable in your `.env` file which collides with one that already exists in your environment, then that variable will be skipped.
619677

620-
```js
621-
const dotenv = require('dotenv')
622-
const variableExpansion = require('dotenv-expand')
623-
const myEnv = dotenv.config()
624-
variableExpansion(myEnv)
678+
If instead, you want to override `process.env` use the `override` option.
679+
680+
```javascript
681+
require('dotenv').config({ override: true })
625682
```
626683
</details>
627684

628685
<details>
629-
<summary>How do I use dotenv with `import`?</summary>
686+
<summary>How can I prevent committing my `.env` file to a Docker build?</summary>
630687

631-
Simply..
688+
Use the [docker prebuild hook](https://dotenvx.com/docs/features/prebuild).
632689

633-
```javascript
634-
// index.mjs (ESM)
635-
import 'dotenv/config' // see https://github.com/motdotla/dotenv#how-do-i-use-dotenv-with-import
636-
import express from 'express'
690+
```bash
691+
# Dockerfile
692+
...
693+
RUN curl -fsS https://dotenvx.sh/ | sh
694+
...
695+
RUN dotenvx prebuild
696+
CMD ["dotenvx", "run", "--", "node", "index.js"]
637697
```
698+
</details>
638699

639-
A little background..
640-
641-
> When you run a module containing an `import` declaration, the modules it imports are loaded first, then each module body is executed in a depth-first traversal of the dependency graph, avoiding cycles by skipping anything already executed.
642-
>
643-
> – [ES6 In Depth: Modules](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/)
644-
645-
What does this mean in plain language? It means you would think the following would work but it won't.
700+
<details>
701+
<summary>How come my environment variables are not showing up for React?</summary>
646702

647-
`errorReporter.mjs`:
648-
```js
649-
class Client {
650-
constructor (apiKey) {
651-
console.log('apiKey', apiKey)
703+
Your React code is run in Webpack, where the `fs` module or even the `process` global itself are not accessible out-of-the-box. `process.env` can only be injected through Webpack configuration.
652704

653-
this.apiKey = apiKey
654-
}
655-
}
705+
If you are using [`react-scripts`](https://www.npmjs.com/package/react-scripts), which is distributed through [`create-react-app`](https://create-react-app.dev/), it has dotenv built in but with a quirk. Preface your environment variables with `REACT_APP_`. See [this stack overflow](https://stackoverflow.com/questions/42182577/is-it-possible-to-use-dotenv-in-a-react-project) for more details.
656706

657-
export default new Client(process.env.API_KEY)
658-
```
659-
`index.mjs`:
660-
```js
661-
// Note: this is INCORRECT and will not work
662-
import * as dotenv from 'dotenv'
663-
dotenv.config()
707+
If you are using other frameworks (e.g. Next.js, Gatsby...), you need to consult their documentation for how to inject environment variables into the client.
708+
</details>
664709

665-
import errorReporter from './errorReporter.mjs' // process.env.API_KEY will be blank!
666-
```
710+
<details>
711+
<summary>Why is the `.env` file not loading my environment variables successfully?</summary>
667712

668-
`process.env.API_KEY` will be blank.
713+
Most likely your `.env` file is not in the correct place. [See this stack overflow](https://stackoverflow.com/questions/42335016/dotenv-file-is-not-loading-environment-variables).
669714

670-
Instead, `index.mjs` should be written as..
715+
Turn on debug mode and try again..
671716

672717
```js
673-
import 'dotenv/config'
674-
675-
import errorReporter from './errorReporter.mjs'
718+
require('dotenv').config({ debug: true })
676719
```
677720

678-
Does that make sense? It's a bit unintuitive, but it is how importing of ES6 modules work. Here is a [working example of this pitfall](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-es6-import-pitfall).
679-
680-
There are two alternatives to this approach:
681-
682-
1. Preload with dotenvx: `dotenvx run -- node index.js` (_Note: you do not need to `import` dotenv with this approach_)
683-
2. Create a separate file that will execute `config` first as outlined in [this comment on #133](https://github.com/motdotla/dotenv/issues/133#issuecomment-255298822)
721+
You will receive a helpful error outputted to your console.
684722
</details>
685723

686724
<details>
@@ -723,46 +761,6 @@ module.exports = {
723761
Alternatively, just use [dotenv-webpack](https://github.com/mrsteele/dotenv-webpack) which does this and more behind the scenes for you.
724762
</details>
725763

726-
<details>
727-
<summary>What about variable expansion?</summary>
728-
729-
Try [dotenv-expand](https://github.com/motdotla/dotenv-expand)
730-
</details>
731-
732-
<details>
733-
<summary>What about syncing and securing .env files?</summary>
734-
735-
Use [dotenvx](https://github.com/dotenvx/dotenvx) to unlock syncing encrypted .env files over git.
736-
</details>
737-
738-
<details>
739-
<summary>What if I accidentally commit my `.env` file to code?</summary>
740-
741-
Remove it, [remove git history](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository) and then install the [git pre-commit hook](https://github.com/dotenvx/dotenvx#pre-commit) to prevent this from ever happening again.
742-
743-
```
744-
brew install dotenvx/brew/dotenvx
745-
dotenvx precommit --install
746-
```
747-
</details>
748-
749-
<details>
750-
<summary>How can I prevent committing my `.env` file to a Docker build?</summary>
751-
752-
Use the [docker prebuild hook](https://dotenvx.com/docs/features/prebuild).
753-
754-
```bash
755-
# Dockerfile
756-
...
757-
RUN curl -fsS https://dotenvx.sh/ | sh
758-
...
759-
RUN dotenvx prebuild
760-
CMD ["dotenvx", "run", "--", "node", "index.js"]
761-
```
762-
</details>
763-
764-
&nbsp;
765-
766764
## Contributing Guide
767765

768766
See [CONTRIBUTING.md](CONTRIBUTING.md)

0 commit comments

Comments
 (0)