Skip to content

Commit 3fcd2fe

Browse files
motdotlamotdotla
committed
update README
1 parent a98ba56 commit 3fcd2fe

File tree

1 file changed

+181
-188
lines changed

1 file changed

+181
-188
lines changed

‎README.md‎

Lines changed: 181 additions & 188 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,6 @@ console.log(process.env) // remove this after you've confirmed it is working
3434

3535
That's it. `process.env` now has the keys and values you defined in your `.env` file:
3636

37-
3837
 
3938

4039
## Advanced
@@ -346,191 +345,6 @@ vestauth agent curl https://as2.dotenvx.com/get?key=KEY
346345

347346
 
348347

349-
## Documentation
350-
351-
Dotenv exposes four functions:
352-
353-
* `config`
354-
* `parse`
355-
* `populate`
356-
357-
### Config
358-
359-
`config` will read your `.env` file, parse the contents, assign it to
360-
[`process.env`](https://nodejs.org/docs/latest/api/process.html#process_process_env),
361-
and return an Object with a `parsed` key containing the loaded content or an `error` key if it failed.
362-
363-
```js
364-
const result = dotenv.config()
365-
366-
if (result.error) {
367-
throw result.error
368-
}
369-
370-
console.log(result.parsed)
371-
```
372-
373-
You can additionally, pass options to `config`.
374-
375-
#### Options
376-
377-
##### path
378-
379-
Default: `path.resolve(process.cwd(), '.env')`
380-
381-
Specify a custom path if your file containing environment variables is located elsewhere.
382-
383-
```js
384-
require('dotenv').config({ path: '/custom/path/to/.env' })
385-
```
386-
387-
By default, `config` will look for a file called .env in the current working directory.
388-
389-
Pass in multiple files as an array, and they will be parsed in order and combined with `process.env` (or `option.processEnv`, if set). The first value set for a variable will win, unless the `options.override` flag is set, in which case the last value set will win. If a value already exists in `process.env` and the `options.override` flag is NOT set, no changes will be made to that value.
390-
391-
```js
392-
require('dotenv').config({ path: ['.env.local', '.env'] })
393-
```
394-
395-
##### quiet
396-
397-
Default: `false`
398-
399-
Suppress runtime logging message.
400-
401-
```js
402-
// index.js
403-
require('dotenv').config({ quiet: false }) // change to true to suppress
404-
console.log(`Hello ${process.env.HELLO}`)
405-
```
406-
407-
```ini
408-
# .env
409-
HELLO=World
410-
```
411-
412-
```sh
413-
$ node index.js
414-
[dotenv@17.0.0] injecting env (1) from .env
415-
Hello World
416-
```
417-
418-
##### encoding
419-
420-
Default: `utf8`
421-
422-
Specify the encoding of your file containing environment variables.
423-
424-
```js
425-
require('dotenv').config({ encoding: 'latin1' })
426-
```
427-
428-
##### debug
429-
430-
Default: `false`
431-
432-
Turn on logging to help debug why certain keys or values are not being set as you expect.
433-
434-
```js
435-
require('dotenv').config({ debug: process.env.DEBUG })
436-
```
437-
438-
##### override
439-
440-
Default: `false`
441-
442-
Override any environment variables that have already been set on your machine with values from your .env file(s). If multiple files have been provided in `option.path` the override will also be used as each file is combined with the next. Without `override` being set, the first value wins. With `override` set the last value wins.
443-
444-
```js
445-
require('dotenv').config({ override: true })
446-
```
447-
448-
##### processEnv
449-
450-
Default: `process.env`
451-
452-
Specify an object to write your environment variables to. Defaults to `process.env` environment variables.
453-
454-
```js
455-
const myObject = {}
456-
require('dotenv').config({ processEnv: myObject })
457-
458-
console.log(myObject) // values from .env
459-
console.log(process.env) // this was not changed or written to
460-
```
461-
462-
### Parse
463-
464-
The engine which parses the contents of your file containing environment
465-
variables is available to use. It accepts a String or Buffer and will return
466-
an Object with the parsed keys and values.
467-
468-
```js
469-
const dotenv = require('dotenv')
470-
const buf = Buffer.from('BASIC=basic')
471-
const config = dotenv.parse(buf) // will return an object
472-
console.log(typeof config, config) // object { BASIC : 'basic' }
473-
```
474-
475-
#### Options
476-
477-
##### debug
478-
479-
Default: `false`
480-
481-
Turn on logging to help debug why certain keys or values are not being set as you expect.
482-
483-
```js
484-
const dotenv = require('dotenv')
485-
const buf = Buffer.from('hello world')
486-
const opt = { debug: true }
487-
const config = dotenv.parse(buf, opt)
488-
// expect a debug message because the buffer is not in KEY=VAL form
489-
```
490-
491-
### Populate
492-
493-
The engine which populates the contents of your .env file to `process.env` is available for use. It accepts a target, a source, and options. This is useful for power users who want to supply their own objects.
494-
495-
For example, customizing the source:
496-
497-
```js
498-
const dotenv = require('dotenv')
499-
const parsed = { HELLO: 'world' }
500-
501-
dotenv.populate(process.env, parsed)
502-
503-
console.log(process.env.HELLO) // world
504-
```
505-
506-
For example, customizing the source AND target:
507-
508-
```js
509-
const dotenv = require('dotenv')
510-
const parsed = { HELLO: 'universe' }
511-
const target = { HELLO: 'world' } // empty object
512-
513-
dotenv.populate(target, parsed, { override: true, debug: true })
514-
515-
console.log(target) // { HELLO: 'universe' }
516-
```
517-
518-
#### options
519-
520-
##### Debug
521-
522-
Default: `false`
523-
524-
Turn on logging to help debug why certain keys or values are not being populated as you expect.
525-
526-
##### override
527-
528-
Default: `false`
529-
530-
Override any environment variables that have already been set.
531-
532-
 
533-
534348
## FAQ
535349

536350
<details><summary>Should I commit my `.env` file?</summary><br/>
@@ -753,9 +567,188 @@ Alternatively, just use [dotenv-webpack](https://github.com/mrsteele/dotenv-webp
753567

754568
&nbsp;
755569

756-
## Contributing Guide
570+
## Docs
571+
572+
Dotenv exposes four functions:
573+
574+
* `config`
575+
* `parse`
576+
* `populate`
577+
578+
### Config
579+
580+
`config` will read your `.env` file, parse the contents, assign it to
581+
[`process.env`](https://nodejs.org/docs/latest/api/process.html#process_process_env),
582+
and return an Object with a `parsed` key containing the loaded content or an `error` key if it failed.
583+
584+
```js
585+
const result = dotenv.config()
586+
587+
if (result.error) {
588+
throw result.error
589+
}
590+
591+
console.log(result.parsed)
592+
```
593+
594+
You can additionally, pass options to `config`.
595+
596+
#### Options
597+
598+
##### path
599+
600+
Default: `path.resolve(process.cwd(), '.env')`
601+
602+
Specify a custom path if your file containing environment variables is located elsewhere.
603+
604+
```js
605+
require('dotenv').config({ path: '/custom/path/to/.env' })
606+
```
607+
608+
By default, `config` will look for a file called .env in the current working directory.
609+
610+
Pass in multiple files as an array, and they will be parsed in order and combined with `process.env` (or `option.processEnv`, if set). The first value set for a variable will win, unless the `options.override` flag is set, in which case the last value set will win. If a value already exists in `process.env` and the `options.override` flag is NOT set, no changes will be made to that value.
611+
612+
```js
613+
require('dotenv').config({ path: ['.env.local', '.env'] })
614+
```
615+
616+
##### quiet
617+
618+
Default: `false`
619+
620+
Suppress runtime logging message.
621+
622+
```js
623+
// index.js
624+
require('dotenv').config({ quiet: false }) // change to true to suppress
625+
console.log(`Hello ${process.env.HELLO}`)
626+
```
627+
628+
```ini
629+
# .env
630+
HELLO=World
631+
```
632+
633+
```sh
634+
$ node index.js
635+
[dotenv@17.0.0] injecting env (1) from .env
636+
Hello World
637+
```
638+
639+
##### encoding
640+
641+
Default: `utf8`
642+
643+
Specify the encoding of your file containing environment variables.
644+
645+
```js
646+
require('dotenv').config({ encoding: 'latin1' })
647+
```
648+
649+
##### debug
650+
651+
Default: `false`
652+
653+
Turn on logging to help debug why certain keys or values are not being set as you expect.
654+
655+
```js
656+
require('dotenv').config({ debug: process.env.DEBUG })
657+
```
658+
659+
##### override
660+
661+
Default: `false`
662+
663+
Override any environment variables that have already been set on your machine with values from your .env file(s). If multiple files have been provided in `option.path` the override will also be used as each file is combined with the next. Without `override` being set, the first value wins. With `override` set the last value wins.
664+
665+
```js
666+
require('dotenv').config({ override: true })
667+
```
668+
669+
##### processEnv
670+
671+
Default: `process.env`
672+
673+
Specify an object to write your environment variables to. Defaults to `process.env` environment variables.
674+
675+
```js
676+
const myObject = {}
677+
require('dotenv').config({ processEnv: myObject })
678+
679+
console.log(myObject) // values from .env
680+
console.log(process.env) // this was not changed or written to
681+
```
682+
683+
### Parse
684+
685+
The engine which parses the contents of your file containing environment
686+
variables is available to use. It accepts a String or Buffer and will return
687+
an Object with the parsed keys and values.
688+
689+
```js
690+
const dotenv = require('dotenv')
691+
const buf = Buffer.from('BASIC=basic')
692+
const config = dotenv.parse(buf) // will return an object
693+
console.log(typeof config, config) // object { BASIC : 'basic' }
694+
```
757695

758-
See [CONTRIBUTING.md](CONTRIBUTING.md)
696+
#### Options
697+
698+
##### debug
699+
700+
Default: `false`
701+
702+
Turn on logging to help debug why certain keys or values are not being set as you expect.
703+
704+
```js
705+
const dotenv = require('dotenv')
706+
const buf = Buffer.from('hello world')
707+
const opt = { debug: true }
708+
const config = dotenv.parse(buf, opt)
709+
// expect a debug message because the buffer is not in KEY=VAL form
710+
```
711+
712+
### Populate
713+
714+
The engine which populates the contents of your .env file to `process.env` is available for use. It accepts a target, a source, and options. This is useful for power users who want to supply their own objects.
715+
716+
For example, customizing the source:
717+
718+
```js
719+
const dotenv = require('dotenv')
720+
const parsed = { HELLO: 'world' }
721+
722+
dotenv.populate(process.env, parsed)
723+
724+
console.log(process.env.HELLO) // world
725+
```
726+
727+
For example, customizing the source AND target:
728+
729+
```js
730+
const dotenv = require('dotenv')
731+
const parsed = { HELLO: 'universe' }
732+
const target = { HELLO: 'world' } // empty object
733+
734+
dotenv.populate(target, parsed, { override: true, debug: true })
735+
736+
console.log(target) // { HELLO: 'universe' }
737+
```
738+
739+
#### options
740+
741+
##### Debug
742+
743+
Default: `false`
744+
745+
Turn on logging to help debug why certain keys or values are not being populated as you expect.
746+
747+
##### override
748+
749+
Default: `false`
750+
751+
Override any environment variables that have already been set.
759752

760753
&nbsp;
761754

0 commit comments

Comments
 (0)