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