|
1 | | -# WIP |
| 1 | +## Configuring webpack |
| 2 | + |
| 3 | +- [Basic Configuration](#basic-configuration) |
| 4 | +- [Chaining](#chaining-advanced) |
| 5 | +- [Inspecting the Config](#inspecting-the-projects-webpack-config) |
| 6 | +- [Using Resolved Config as a File](#using-resolved-config-as-a-file) |
2 | 7 |
|
3 | 8 | ### Basic Configuration |
4 | 9 |
|
5 | | -### Chaining |
| 10 | +The easiest way to tweak the webpack config is provide an object to the `configureWebpack` option in `vue.config.js`: |
| 11 | + |
| 12 | +``` js |
| 13 | +// vue.config.js |
| 14 | +module.exports = { |
| 15 | + configureWebpack: { |
| 16 | + plugins: [ |
| 17 | + new MyAwesomeWebpackPlugin() |
| 18 | + ] |
| 19 | + } |
| 20 | +} |
| 21 | +``` |
| 22 | + |
| 23 | +The object will be merged into the final webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge). |
| 24 | + |
| 25 | +If you need conditional behavior based on the environment, or want to directly mutate the config, use a function (which will be lazy evaluated after the env variables are set). The function receives the resolved config as the argument. Inside the function, you can either mutate the config directly, OR return an object which will be merged: |
| 26 | + |
| 27 | +``` js |
| 28 | +// vue.config.js |
| 29 | +module.exports = { |
| 30 | + configureWebpack: config => { |
| 31 | + if (process.env.NODE_ENV === 'production') { |
| 32 | + // mutate config for production... |
| 33 | + } else { |
| 34 | + // mutate for development... |
| 35 | + } |
| 36 | + } |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +### Chaining (Advanced) |
| 41 | + |
| 42 | +The internal webpack config is maintained using [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). The library provides an abstraction over the raw webpack config, with the ability to define named loader rules and named plugins, and later "tap" into those rules and modify their options. |
| 43 | + |
| 44 | +This allows us finer-grained control over the internal config. Here are some examples: |
| 45 | + |
| 46 | +#### Transpiling a Dependency Module |
| 47 | + |
| 48 | +By default the Babel configuration skips |
| 49 | + |
| 50 | +``` js |
| 51 | +// vue.config.js |
| 52 | +module.exports = { |
| 53 | + chainWebpack: config => { |
| 54 | + config |
| 55 | + .rule('js') |
| 56 | + .include |
| 57 | + .add(/some-module-to-transpile/) |
| 58 | + } |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +#### Modifying Plugin Options |
| 63 | + |
| 64 | +``` js |
| 65 | +// vue.config.js |
| 66 | +module.exports = { |
| 67 | + chainWebpack: config => { |
| 68 | + config |
| 69 | + .plugin('html') |
| 70 | + .tap(args => { |
| 71 | + return [/* new args to pass to html-webpack-plugin's constructor */] |
| 72 | + }) |
| 73 | + } |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +You will need to familiarize yourself with [webpack-chain's API](https://github.com/mozilla-neutrino/webpack-chain#getting-started) and [read some source code](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-service/lib/config) in order to understand how to leverage the full power of this option, but it gives you a more expressive and safer way to modify the webpack config than directly mutation values. |
| 78 | + |
| 79 | +### Inspecting the Project's Webpack Config |
| 80 | + |
| 81 | +Since `@vue/cli-service` abstracts away the webpack config, it may be more difficult to understand what is included in the config, especially when you are trying to make tweaks yourself. |
| 82 | + |
| 83 | +`vue-cli-service` exposes the `inspect` command for inspecting the resolved webpack config. The global `vue` binary also provides the `inspect` command, and it simply proxies to `vue-cli-service inspect` in your project. |
| 84 | + |
| 85 | +The command prints to stdout by default, so you can redirect that into a file for easier inspection: |
| 86 | + |
| 87 | +``` sh |
| 88 | +vue inspect > output.js |
| 89 | +``` |
| 90 | + |
| 91 | +Note the output is not a valid webpack config file, it's a serialized format only meant for inspection. |
| 92 | + |
| 93 | +You can also inspect a certain path of the config to narrow it down: |
| 94 | + |
| 95 | +``` sh |
| 96 | +# only inspect the first rule |
| 97 | +vue inspect module.rules.0 |
| 98 | +``` |
6 | 99 |
|
7 | 100 | ### Using Resolved Config as a File |
| 101 | + |
| 102 | +Some external tools may need access to the resolved webpack config as a file, for example IDEs or command line tools that expects a webpack config path. In that case you can use the following path: |
| 103 | + |
| 104 | +``` |
| 105 | +<projectRoot>/node_modules/@vue/cli-service/webpack.config.js |
| 106 | +``` |
| 107 | + |
| 108 | +This file dynamically resolves and exports the exact same webpack config used in `vue-cli-service` commands, including those from plugins and even your custom configurations. |
0 commit comments