Sponsor webpack and get apparel from the official shop or get stickers here! All proceeds go to our open collective!

ag-grid is proud to partner with webpack


[![npm][npm]][npm-url] [![node][node]][node-url] [![deps][deps]][deps-url] [![tests][tests]][tests-url] [![chat][chat]][chat-url]

A webpack configuration loader.

This module utilizes cosmiconfig which supports declaring a webpack configuration in a number of different file formats including; .webpackrc, webpack.config.js, and a webpack property in a package.json.

config-loader supports configuration modules which export an Object, Array, Function, Promise, and Function which returns a Promise.

The module also validates found configurations against webpack's options schema to ensure that the configuration is correct before webpack attempts to use it.


This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

To begin, you'll need to install config-loader:

$ npm install @webpack-contrib/config-loader --save-dev

And get straight to loading a config:

const loader = require('@webpack-contrib/config-loader');
const options = { ... };

loader(options).then((result) => {
  // ...
  // result = { config: Object, configPath: String }


When using a configuration file that exports a Function, users of webpack-cli have become accustom to the function signature:

function config (env, argv)

webpack-cli provides any CLI flags prefixed with --env as a single object in the env parameter, which is an unnecessary feature. Environment Variables have long served the same purpose, and are easily accessible within a Node environment.

As such, config-loader does not call Function configs with the env parameter. Rather, it makes calls with only the argv parameter.

Supported Compilers

This module can support non-standard JavaScript file formats when a compatible compiler is registered via the require option. If the option is defined, config-loader will attempt to require the specified module(s) before the target config is found and loaded.

As such, config-loader will also search for the following file extensions; .js, .es6, .flow, .mjs, and .ts.

The module is also tested with the following compilers:

Note: Compilers are not part of or built-into this module. To use a specific compiler, you must install it and specify its use by using the --require CLI flag.



Returns a Promise, which resolves with an Object containing:


Type: Object

Contains the actual configuration object.


Type: String

Contains the full, absolute filesystem path to the configuration file.



Type: String Default: undefined

Specifies an absolute path to a valid configuration file on the filesystem.


Type: String Default: process.cwd()

Specifies an filesystem path from which point config-loader will begin looking for a configuration file.


Type: String Default: undefined

Specifies a compiler to use when loading modules from files containing the configuration. For example:

const loader = require('@webpack-contrib/config-loader');
const options = { require: 'ts-node/register' };

loader(options).then((result) => { ... });

See Supported Compilers for more information.


Please take a moment to read our contributing guidelines if you haven't yet done so.