feat(webpack): add getWebpackConfig hook (#297)

* add getWebpackConfig hook

* add /docs/working-with-webpack.html

* tweaks

Author: egoist

packages/saber/lib/index.js

@@ -33,7 +33,8 @@ class Saber {
       beforeRun: new AsyncSeriesHook(),
       onUpdateConfigFile: new AsyncSeriesHook(),
       // Extend webpack config
-      chainWebpack: new SyncHook(['config', 'opts']),
+      chainWebpack: new SyncHook(['webpackChain', 'opts']),
+      getWebpackConfig: new SyncWaterfallHook(['config', 'opts']),
       // Extend markdown-it config
       chainMarkdown: new SyncHook(['config']),
       emitRoutes: new AsyncSeriesHook(),
@@ -272,10 +273,11 @@ class Saber {
     return this.resolveCwd(this.config.build.outDir, ...args)
   }
 
-  createWebpackChain(opts) {
+  getWebpackConfig(opts) {
     opts = Object.assign({ type: 'client' }, opts)
-    const config = require('./webpack/webpack.config')(this, opts)
-    this.hooks.chainWebpack.call(config, opts)
+    const chain = require('./webpack/webpack.config')(this, opts)
+    this.hooks.chainWebpack.call(chain, opts)
+    const config = this.hooks.getWebpackConfig.call(chain.toConfig(), opts)
     return config
   }
 

packages/saber/vue-renderer/lib/index.js

@@ -228,12 +228,8 @@ class VueRenderer {
   }
 
   async build() {
-    const clientConfig = this.api
-      .createWebpackChain({ type: 'client' })
-      .toConfig()
-    const serverConfig = this.api
-      .createWebpackChain({ type: 'server' })
-      .toConfig()
+    const clientConfig = this.api.getWebpackConfig({ type: 'client' })
+    const serverConfig = this.api.getWebpackConfig({ type: 'server' })
 
     // Remove dist-client
     await fs.remove(this.api.resolveCache('dist-client'))
@@ -375,9 +371,7 @@ class VueRenderer {
 
     this.api.hooks.onCreateServer.call(server)
 
-    const clientConfig = this.api
-      .createWebpackChain({ type: 'client' })
-      .toConfig()
+    const clientConfig = this.api.getWebpackConfig({ type: 'client' })
 
     clientConfig.plugins.push(new webpack.HotModuleReplacementPlugin())
 

website/pages/docs/saber-instance.md

@@ -172,10 +172,19 @@ Called after emitting the routes file.
 
 - Hook Type: `SyncHook`
 - Params:
-  - `config`: `WebpackChain`
+  - `webpackChain`: `WebpackChain`
   - `opts`: `{ type: 'client' | 'server' }`
 
-Called to get the webpack config before creating webpack compiler.
+Called with the `webpack-chain` instance before creating webpack compiler.
+
+### `getWebpackConfig`
+
+- Hook Type: `SyncWaterfallHook`
+- Params:
+  - `config`: `WebpackConfig`
+  - `opts`: `{ type: 'client' | 'server' }`
+
+Called to get the webpack config before creating webpack compiler. You should return the webpack config object in this hook.
 
 ### `onCreateServer`
 

website/pages/docs/working-with-webpack.md

@@ -0,0 +1,40 @@
+---
+title: Working with Webpack
+layout: docs
+---
+
+## Simple Configuration
+
+The easiest way to tweak webpack configuration is using the [`getWebpackConfig`](saber-instance.md#getwebpackconfig) hook in your [`saber-node.js`](node-apis.md) like this:
+
+```js
+exports.getWebpackConfig = function(config, { type }) {
+  // e.g. Adding a webpack plugin
+  config.plugins.push(new SomeWebpackPlugin())
+
+  // `type` is either `client` or `server`
+  if (type === 'client') {
+    config.plugins.push(new SomeWebpackPluginForClientBuild())
+  }
+
+  // You must return the `config`!
+  return config
+}
+```
+
+## Advanced Configuration
+
+You can use [webpack-chain](https://github.com/neutrinojs/webpack-chain) to tweak webpack configuration in a more predictable way.
+
+> webpack's core configuration is based on creating and modifying a potentially unwieldy JavaScript object. While this is OK for configurations on individual projects, trying to share these objects across projects and make subsequent modifications gets messy, as you need to have a deep understanding of the underlying object structure to make those changes.
+>
+> webpack-chain attempts to improve this process by providing a chainable or fluent API for creating and modifying webpack configurations. Key portions of the API can be referenced by user-specified names, which helps to standardize how to modify a configuration across projects.
+
+Using the [chainWebpack](saber-instance.md#chainwebpack) hook in [`saber-node.js`](node-apis.md) to access the webpack-chain instance:
+
+```js
+exports.chainWebpack = function(chain) {
+  // e.g. Resolve .css files
+  chain.resolve.extensions.add('.css')
+}
+```

website/saber-config.js

@@ -33,6 +33,7 @@ module.exports = {
           { title: 'Manipulating <head>', link: '/docs/manipulating-head.html' },
           { title: 'Page Transition', link: '/docs/page-transition.html' },
           { title: 'Internationalization', link: '/docs/i18n.html' },
+          { title: 'Working with Webpack', link: '/docs/working-with-webpack.html' },
           { title: 'Deployment', link: '/docs/deployment.html' }
         ]
       },