1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
<div align="center">
<a href="https://github.com/webpack/webpack">
<img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
</a>
</div>
[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![chat][chat]][chat-url]
# config-loader
A webpack configuration loader.
This module utilizes [`cosmiconfig`](https://github.com/davidtheclark/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.
## Requirements
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`:
```console
$ npm install @webpack-contrib/config-loader --save-dev
```
And get straight to loading a config:
```js
const loader = require('@webpack-contrib/config-loader');
const options = { ... };
loader(options).then((result) => {
// ...
// result = { config: Object, configPath: String }
});
```
## Extending Configuration Files
This module supports extending webpack configuration files with
[ESLint-style](https://eslint.org/docs/user-guide/configuring#extending-configuration-files)
`extends` functionality. This feature allows users to create a "base" config and
in essence, "inherit" from that base config in a separate config. A bare-bones
example:
```js
// base.config.js
module.exports = {
name: 'base',
mode: 'development',
plugins: [...]
}
```
```js
// webpack.config.js
module.exports = {
extends: path.join(..., 'base-config.js'),
name: 'dev'
```
The resulting configuration object would resemble:
```js
// result
{
name: 'dev',
mode: 'development',
plugins: [...]
}
```
The `webpack.config.js` file will be intelligently extended with properties
from `base.config.js`.
The `extends` property also supports naming installed NPM modules which export
webpack configurations. Various configuration properties can also be filtered in
different ways based on need.
[Read More about Extending Configuration Files](./docs/EXTENDS.md)
## Gotchas
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](https://en.wikipedia.org/wiki/Environment_variable#Syntax)
have long served the same purpose, and are easily accessible within a
[Node environment](https://nodejs.org/api/process.html#process_process_env).
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:
- [`babel-register`](https://github.com/babel/babel/tree/6.x/packages/babel-register)
- [`flow-remove-types/register`](https://github.com/flowtype/flow-remove-types)
- [`ts-node/register`](https://www.npmjs.com/package/ts-node)
_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._
## API
### loader([options])
Returns a `Promise`, which resolves with an `Object` containing:
#### `config`
Type: `Object`
Contains the actual configuration object.
#### `configPath`
Type: `String`
Contains the full, absolute filesystem path to the configuration file.
## Options
#### `allowMissing`
Type: `Boolean`
Default: `false`
Instructs the module to allow a missing config file, and returns an `Object`
with empty `config` and `configPath` properties in the event a config file was
not found.
### `configPath`
Type: `String`
Default: `undefined`
Specifies an absolute path to a valid configuration file on the filesystem.
### `cwd`
Type: `String`
Default: `process.cwd()`
Specifies an filesystem path from which point `config-loader` will begin looking
for a configuration file.
### `require`
Type: `String | Array[String]`
Default: `undefined`
Specifies compiler(s) to use when loading modules from files containing the
configuration. For example:
```js
const loader = require('@webpack-contrib/config-loader');
const options = { require: 'ts-node/register' };
loader(options).then((result) => { ... });
```
See
[Supported Compilers](https://github.com/webpack-contrib/config-loader#supported-compilers)
for more information.
### `schema`
Type: `Object`
Default: `undefined`
An object containing a valid
[JSON Schema Definition](http://json-schema.org/latest/json-schema-validation.html).
By default, `config-loader` validates your webpack config against the
[webpack config schema](https://github.com/webpack/webpack/blob/master/schemas/WebpackOptions.json).
However, it can be useful to append additional schema data to allow configs,
which contain properties not present in the webpack schema, to pass validation.
## Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
#### [CONTRIBUTING](./.github/CONTRIBUTING)
## License
#### [MIT](./LICENSE)
[npm]: https://img.shields.io/npm/v/@webpack-contrib/config-loader.svg
[npm-url]: https://npmjs.com/package/@webpack-contrib/config-loader
[node]: https://img.shields.io/node/v/@webpack-contrib/config-loader.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack-contrib/config-loader.svg
[deps-url]: https://david-dm.org/webpack-contrib/config-loader
[tests]: https://img.shields.io/circleci/project/github/webpack-contrib/config-loader.svg
[tests-url]: https://circleci.com/gh/webpack-contrib/config-loader
[cover]: https://codecov.io/gh/webpack-contrib/config-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/config-loader
[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack
|
