1 |
|
2 | [![npm][npm]][npm-url]
|
3 | [![node][node]][node-url]
|
4 | [![deps][deps]][deps-url]
|
5 | [![tests][tests]][tests-url]
|
6 | [![coverage][cover]][cover-url]
|
7 | [![chat][chat]][chat-url]
|
8 | [![size][size]][size-url]
|
9 |
|
10 | # webpack-command
|
11 |
|
12 | For a truly fast, teensy, squeaky clean Webpack CLI - try [webpack-nano](https://www.npmjs.com/package/webpack-nano).
|
13 |
|
14 | > Note: webpack-command is now being maintained on [this fork](https://github.com/shellscape/webpack-command), and will be open to Pull Requests and Issues for users that prefer this CLI. The webpack-contrib org has chosen to drop support for this module and is no longer actively maintaining it.
|
15 |
|
16 | A superior CLI experience for webpack. Modular and opinionated.
|
17 |
|
18 | For users coming from `webpack-cli`, please read about
|
19 | [the differences](#differences-with-webpack-cli) between this module and
|
20 | `webpack-cli`.
|
21 |
|
22 | ## Requirements
|
23 |
|
24 | This module requires a minimum of Node v6.14.0 and Webpack v4.0.0.
|
25 |
|
26 | `webpack-command` and `webpack-cli` cannot be installed at the same time, as
|
27 | they both export a bin file named `webpack`. When trying `webpack-command`,
|
28 | please `npm uninstall webpack-cli` first.
|
29 |
|
30 | ## Benefits
|
31 |
|
32 | `webpack-command` has many advantages over other CLI experiences for `webpack`.
|
33 | These include:
|
34 |
|
35 | - [Extendable Webpack Configurations](#extendable-webpack-configurations). A
|
36 | configuration file can extend the properties and collections from base
|
37 | configurations, and are filtered intelligently.
|
38 | - Custom Reporters 🤯
|
39 | - A beautiful default user experience with output driven by
|
40 | [`webpack-stylish`](https://www.npmjs.com/package/webpack-stylish)
|
41 | - Support for `webpack` configuration in any language or compiler that provides
|
42 | a `require` hook
|
43 | - Support for `webpack` configuration in `JSON`, `YAML`, or `JavaScript`
|
44 | - Validation of commands, entries, and flags before further execution
|
45 | - Extensible third-party commands. Include only what you need!
|
46 | - A full test suite with 220 tests and 95% coverage (so close to 100% 💪)
|
47 | - A ~~93%~~ 24% smaller package cost versus `webpack-cli` (it used to be 93%,
|
48 | they got wise after _webpack-command_ was released)
|
49 | - Highly focused on the User Experience and detail
|
50 |
|
51 | And last but not least, Did-You-Mean suggestions for flags:
|
52 |
|
53 | <img width="427" src="https://raw.githubusercontent.com/shellscape/webpack-command/master/assets/did-you-mean.png" alt="did you mean">
|
54 |
|
55 | ## Getting Started
|
56 |
|
57 | To begin, you'll need to install `webpack-command`:
|
58 |
|
59 | ```console
|
60 | $ npm install webpack-command --save-dev
|
61 | ```
|
62 |
|
63 | ## CLI
|
64 |
|
65 | The primary binary for webpack-command is `wp` (because who doesn't like to save
|
66 | keystrokes!?) Although, you may also use the `webpack` binary as per usual if
|
67 | your setup installs this module _after_ webpack, and the two don't conflict.
|
68 |
|
69 | ```console
|
70 | $ wp --help
|
71 |
|
72 | A superior CLI experience for webpack. Lightweight, modular, and opinionated.
|
73 |
|
74 | Usage
|
75 | $ webpack [<config>, ...options]
|
76 | $ webpack <entry-file> [...<entry-file>] <output-file>
|
77 | $ webpack <command> [...options]
|
78 |
|
79 | Options
|
80 | --context The root directory for resolving entry point and stats
|
81 | --debug Switch loaders to debug mode
|
82 | --devtool Enable devtool for better debugging experience.
|
83 | e.g. --devtool eval-cheap-module-source-map
|
84 | --entry The entry point
|
85 | --help Show usage information and the options listed here
|
86 | --log-level Limit all process console messages to a specific level and above
|
87 | Levels: trace, debug, info, warn, error, silent
|
88 | --log-time Instruct the logger for webpack-serve and dependencies to display a timestamp
|
89 | --progress Instructs webpack to track and display build progress
|
90 | --reporter Specifies the reporter to use for generating console output for a build
|
91 | --require Preload one or more modules before loading the webpack configuration
|
92 | Typically used for language-specific require hooks
|
93 | --run-dev An alias for --debug --devtool eval-cheap-module-source-map --output-pathinfo
|
94 | --run-prod An alias for --optimize-minimize --define process.env.NODE_ENV="production"
|
95 | --version Display the webpack-command version
|
96 | --watch Watch the filesystem for changes
|
97 |
|
98 | Advanced
|
99 | --bail Abort the compilation on first error
|
100 | --cache Enable in memory caching
|
101 | --define Define any free var in the bundle
|
102 | --hot Enables Hot Module Replacement
|
103 | --plugin Load this plugin
|
104 | --prefetch Prefetch this request
|
105 | e.g. --prefetch ./file.js
|
106 | --profile Profile the compilation and include information in stats
|
107 | --provide Provide these modules as free vars in all modules
|
108 | e.g. --provide.jQuery jquery
|
109 | --records-input-path Path to the records file (reading)
|
110 | --records-output-path Path to the records file (writing)
|
111 | --records-path Path to the records file
|
112 | --target The targeted execution environment
|
113 | --watch-aggregate-timeout Timeout for gathering changes while watching
|
114 | --watch-poll The polling interval for watching (also enable polling)
|
115 | --watch-stdin Exit the process when stdin is closed
|
116 |
|
117 | Configuration File
|
118 | --config Path to the config file
|
119 | --config-name Name of the config to use
|
120 | --config-register Deprecated. Please use --require.
|
121 | --mode Specifies the build mode to use; development or production
|
122 |
|
123 | Modules
|
124 | --module-bind Bind an extension to a loader
|
125 | --module-bind-post Bind an extension to a postLoader
|
126 | --module-bind-pre Bind an extension to a preLoader
|
127 |
|
128 | Optimization
|
129 | --optimize-max-chunks Try to keep the chunk count below a limit
|
130 | --optimize-min-chunk-size Try to keep the chunk size above a limit
|
131 | --optimize-minimize Minimize javascript and switches loaders to minimizing
|
132 |
|
133 | Output
|
134 | --output The output path and file for compilation assets
|
135 | --output-chunk-filename The output filename for additional chunks
|
136 | --output-filename The output filename of the bundle
|
137 | --output-jsonp-function The name of the JSONP function used for chunk loading
|
138 | --output-library Expose the exports of the entry point as library
|
139 | --output-library-target The type for exposing the exports of the entry point as library
|
140 | --output-path The output path for compilation assets
|
141 | --output-pathinfo Include a comment with the request for every dependency (require, import, etc.)
|
142 | --output-public-path The public path for the assets
|
143 | --output-source-map-filename The output filename for the SourceMap
|
144 |
|
145 | Resolver
|
146 | --resolve-alias Setup a module alias for resolving
|
147 | e.g. --resolve-alias.jquery jquery.plugin
|
148 | --resolve-extensions Setup extensions that should be used to resolve modules
|
149 | e.g. .es6,.js
|
150 | --resolve-loader-alias Setup a loader alias for resolving
|
151 |
|
152 |
|
153 | For further documentation, visit https://webpack.js.org/api/cli
|
154 |
|
155 | Commands
|
156 | help
|
157 | teach
|
158 |
|
159 | Type `webpack help <command>` for more information
|
160 | ```
|
161 |
|
162 | As a convenience for alternative package managers, the `webpack-command` binary
|
163 | is also installed with this package.
|
164 |
|
165 | ## Extendable Webpack Configurations
|
166 |
|
167 | This module supports extending webpack configuration files with
|
168 | [ESLint-style](https://eslint.org/docs/user-guide/configuring#extending-configuration-files)
|
169 | `extends` functionality. This feature allows users to create a "base" config and
|
170 | in essence, "inherit" from that base config in a separate config. A bare-bones
|
171 | example:
|
172 |
|
173 | ```js
|
174 | // base.config.js
|
175 | module.exports = {
|
176 | name: 'base',
|
177 | mode: 'development',
|
178 | plugins: [...]
|
179 | }
|
180 | ```
|
181 |
|
182 | ```js
|
183 | // webpack.config.js
|
184 | module.exports = {
|
185 | extends: path.join(..., 'base-config.js'),
|
186 | name: 'dev'
|
187 | ```
|
188 |
|
189 | The resulting configuration object would resemble:
|
190 |
|
191 | ```js
|
192 | {
|
193 | name: 'dev',
|
194 | mode: 'development',
|
195 | plugins: [...]
|
196 | }
|
197 | ```
|
198 |
|
199 | [Read More about Extending Configuration Files](https://github.com/shellscape/config-loader/blob/master/docs/EXTENDS.md)
|
200 |
|
201 | ## Commands
|
202 |
|
203 | `webpack-command` allows users to extend the `webpack` CLI experience by
|
204 | including a few helpful built-in commands, and providing a means to develop
|
205 | third-party commands.
|
206 |
|
207 | ### Built-In Commands
|
208 |
|
209 | - [Help Command](docs/HelpCommand.md)
|
210 | - [Teach Command](docs/TeachCommand.md)
|
211 |
|
212 | ## Flags
|
213 |
|
214 | For more documentation on flags, please see the
|
215 | [`webpack-cli` documentation](https://webpack.js.org/api/cli/).
|
216 |
|
217 | ## Differences With `webpack-cli`
|
218 |
|
219 | While this project aims for parity with `webpack-cli` in nearly all aspects,
|
220 | there are some notable differences. Included in those differences is the note
|
221 | that this module includes the bare minimum of commands to provide a `webpack`
|
222 | CLI. Commands like `init`, `migrate`, and `update` are relegated to separate,
|
223 | user-installed modules.
|
224 |
|
225 | That said, the following differences should also be noted:
|
226 |
|
227 | ### The `--env` Flag is Nuked
|
228 |
|
229 | [Environment Variables](https://en.wikipedia.org/wiki/Environment_variable) have
|
230 | been around a very, very long time. `webpack-cli` chose to introduce a feature
|
231 | that let users specify environment variables via a flag. This module does not
|
232 | include that feature. Instead, users should make use of environment variables
|
233 | the traditional, standard way:
|
234 |
|
235 | `$ NEAT_VAR=woo webpack ...`
|
236 |
|
237 | And access the values via `process.env`. Alternatively, if users are in need of
|
238 | cross-platform environment variables, a tool such as
|
239 | [`cross-env`](https://www.npmjs.com/package/cross-env) should be leveraged.
|
240 |
|
241 | ### Key=Value Pairs
|
242 |
|
243 | Certain flags passed in `webpack-cli` allow for a key-value pair for
|
244 | pairing an alias with the alias value. e.g. `--entry name=file`. This module
|
245 | adopts a CLI-standard approach by using the syntax `--flag.key value` instead,
|
246 | and does not support the `key=value` syntax.
|
247 |
|
248 | ### Entries
|
249 |
|
250 | Specifying entries by either flag (`--flag`) or input (`webpack <file>`) require
|
251 | that the file or directory specified exist.
|
252 |
|
253 | Entries passed with a comma-separated value `--entry file,file2` are deprecated
|
254 | and should be migrated to use the CLI-standard `--entry file --entry file2`
|
255 | syntax.
|
256 |
|
257 | Entries passed by flag in `webpack-cli` using `--entry name=file` should be
|
258 | migrated to use the `--entry.name file` syntax.
|
259 |
|
260 | ### Resolve Alias
|
261 |
|
262 | Resolve aliases passed by flag in `webpack-cli` using
|
263 | `--resolve-alias alias=value` should be migrated to use the `--resolve-alias.{alias} {value}`
|
264 | syntax.
|
265 |
|
266 | ### Resolve Loader Alias
|
267 |
|
268 | Resolve aliases passed by flag in `webpack-cli` using
|
269 | `--resolve-loader-alias alias=value` should be migrated to use the
|
270 | `--resolve-loader-alias.alias value` syntax.
|
271 |
|
272 | ## Reporters
|
273 |
|
274 | `webpack-command` supports custom, user-defined reporters which allow users
|
275 | full control over how build data is presented. By default, it ships with two
|
276 | available reporters:
|
277 |
|
278 | #### `basic`
|
279 |
|
280 | Displays the default `webpack` output, the same you'll see
|
281 | using `webpack-cli`.
|
282 |
|
283 | #### `stylish`
|
284 |
|
285 | The **default** reporter and displays beautiful output using the same code
|
286 | that drives [`webpack-stylish`](https://www.npmjs.com/package/webpack-stylish).
|
287 |
|
288 | Building your own reporter is as easy as inheriting from the `Reporter` class
|
289 | located at `lib/reporters/Reporter.js`.
|
290 |
|
291 | ## Configuration Languages and Compilers
|
292 |
|
293 | `webpack-command` allows users to leverage any language that provides a require
|
294 | hook. To leverage this feature, define your configs as such for the following
|
295 | languages/compilers:
|
296 |
|
297 | - Babel ES6 Modules: `webpack.config.js` or `webpack.config.es6`, and use
|
298 | `--require babel-register`
|
299 | - Flow: `webpack.config.js` or `webpack.config.flow`, and use
|
300 | `--require flow-remove-types/register`
|
301 | - TypeScript: `webpack.config.ts`, and use `--require ts-node/register`
|
302 |
|
303 | Other hooks may work for additional language or compiler support.
|
304 |
|
305 | _Note: Compilers are not part of, nor built-into this module. To use a specific
|
306 | compiler, you must install it first._
|
307 |
|
308 | ## Gotchas
|
309 |
|
310 | Any entry files specified will overwrite entries in a `webpack.config.js` file
|
311 | as of [this Pull Request](https://github.com/webpack/webpack-cli/pull/358) in
|
312 | `webpack-cli`.
|
313 |
|
314 | ## Contributing
|
315 |
|
316 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
317 |
|
318 | #### [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
319 |
|
320 | ## License
|
321 |
|
322 | #### [MIT](./LICENSE)
|
323 |
|
324 | [npm]: https://img.shields.io/npm/v/webpack-command.svg
|
325 | [npm-url]: https://npmjs.com/package/webpack-command
|
326 |
|
327 | [node]: https://img.shields.io/node/v/webpack-command.svg
|
328 | [node-url]: https://nodejs.org
|
329 |
|
330 | [deps]: https://david-dm.org/shellscape/webpack-command.svg
|
331 | [deps-url]: https://david-dm.org/shellscape/webpack-command
|
332 |
|
333 | [tests]: https://img.shields.io/circleci/project/github/shellscape/webpack-command.svg
|
334 | [tests-url]: https://circleci.com/gh/shellscape/webpack-command
|
335 |
|
336 | [cover]: https://codecov.io/gh/shellscape/webpack-command/branch/master/graph/badge.svg
|
337 | [cover-url]: https://codecov.io/gh/shellscape/webpack-command
|
338 |
|
339 | [chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
|
340 | [chat-url]: https://gitter.im/webpack/webpack
|
341 |
|
342 | [size]: https://packagephobia.now.sh/badge?p=webpack-command
|
343 | [size-url]: https://packagephobia.now.sh/result?p=webpack-command |
\ | No newline at end of file |