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