Repository files navigation

A secure webpack plugin that supports dotenv and other environment variables andonly exposes what you choose and use.

Include the package locally in your repository.

npm install dotenv-webpack --save-dev

dotenv-webpack wrapsdotenv andWebpack.DefinePlugin. As such, it does a text replace in the resulting bundle for any instances ofprocess.env.

Your.env files can include sensitive information. Because of this,dotenv-webpack will only expose environment variables that areexplicitly referenced in your code to your final bundle.

Interested in taking your environments to the next level? Check out theDotenv Organization.

The plugin can be installed with little-to-no configuration needed. Once installed, you can access the variables within your code usingprocess.env as you would withdotenv.

The example below shows a standard use-case.

// .envDB_HOST=127.0.0.1DB_PASS=foobarS3_API=mysecretkey

// webpack.config.jsconstDotenv=require('dotenv-webpack');module.exports={  ...plugins:[newDotenv()]...};

// file1.jsconsole.log(process.env.DB_HOST);// '127.0.0.1'

// bundle.jsconsole.log('127.0.0.1');

Note: the.env values forDB_PASS andS3_API areNOT present in our bundle, as they were never referenced (asprocess.env.[VAR_NAME]) in the code.

By allowing you to define exactly where you are loading environment variables from and bundling only variables in your project that are explicitly referenced in your code, you can be sure that only what you need is included and you do not accidentally leak anything sensitive.

Add.env to your.gitignore file

Due to the fact that we usewebpack.DefinePlugin under the hood, we cannot support destructing as that breaks how this plugin is meant to be used. Because of this, please reference your variables without destructing. For more information about this, please review the issuehere.

process.env is not polyfilled in Webpack 5+, leading to errors in environments whereprocess isnull (browsers).

We automatically replace any remainingprocess.envs in these environments with"MISSING_ENV_VAR" to avoid these errors.

When theprefix option is set,process.envs will not be stubbed.

If you are running into issues where you or another package you use interfaces withprocess.env, it might be best to setignoreStub: true and make sure you always reference variables that exist within your code (Seethis issue for more information).

Use the following properties to configure your instance.

• path ('./.env') - The path to your environment variables. This same path applies to the.env.example and.env.defaults files.Read more here.
• safe (false) - If true, load '.env.example' to verify the '.env' variables are all set. Can also be a string to a different file.
• allowEmptyValues (false) - Whether to allow empty strings in safe mode. If false, will throw an error if any env variables are empty (but only if safe mode is enabled).
• systemvars (false) - Set to true if you would rather load all system variables as well (useful for CI purposes).
• silent (false) - If true, all warnings will be suppressed.
• expand (false) - Allows your variables to be "expanded" for reusability within your.env file.
• defaults (false) - Adds support fordotenv-defaults. If set totrue, uses./.env.defaults. If a string, uses that location for a defaults file. Read more atnpm.
• ignoreStub (false) - Override the automatic check whether to stubprocess.env.Read more here.
• prefix ('process.env.') - The prefix to use before the name of your env variables.

The following example shows how to set any/all arguments.

module.exports={  ...plugins:[newDotenv({path:'./some.other.env',// load this now instead of the ones in '.env'safe:true,// load '.env.example' to verify the '.env' variables are all set. Can also be a string to a different file.allowEmptyValues:true,// allow empty variables (e.g. `FOO=`) (treat it as empty string, rather than missing)systemvars:true,// load all the predefined 'process.env' variables which will trump anything local per dotenv specs.silent:true,// hide any errorsdefaults:false,// load '.env.defaults' as the default values if empty.prefix:'import.meta.env.'// reference your env variables as 'import.meta.env.ENV_VAR'.})]...};

As previously mentioned, it is possible to customize thepath where the.env file is located as well as itsfilename from the plugin settings:

module.exports={  ...plugins:[newDotenv({path:'./some.other.env',})]...};

It is important to mention that this same path and filename will be used for the location of the.env.example and.env.defaults files if they are configured, this will only add the.example and.defaults suffixes respectively:

module.exports={  ...plugins:[newDotenv({path:'../../path/to/other.env',safe:true,// load '../../path/to/other.env.example'defaults:true,// load '../../path/to/other.env.defaults'})]...};

This is especially useful when working withMonorepos where the same configuration can be shared within all sub-packages of the repository:

.├── packages/│   ├── app/│   │   └── webpack.config.js# { path: '../../.env' }│   └── libs/│       └── webpack.config.js# { path: '../../.env' }├── .env├── .env.example└── .env.defaults

MIT