|
| 1 | +# Build Configuration |
| 2 | + |
| 3 | +The webpack config for an SSR project will be similar to a client-only project. If you're not familiar with configuring webpack, you can find more information in the documentation for [Vue CLI](https://cli.vuejs.org/guide/webpack.html#working-with-webpack) or [configuring Vue Loader manually](https://vue-loader.vuejs.org/guide/#manual-setup). |
| 4 | + |
| 5 | +## Key Differences with Client-Only Builds |
| 6 | + |
| 7 | +1. We need to create a [webpack manifest](https://webpack.js.org/concepts/manifest/) for our server-side code. This is a JSON file that webpack keeps to track how all the modules map to the output bundles. |
| 8 | + |
| 9 | +2. We should [externalize application dependencies](https://webpack.js.org/configuration/externals/). This makes the server build much faster and generates a smaller bundle file. When doing this, we have to exclude dependencies that need to be processed by webpack (like `.css`. or `.vue` files). |
| 10 | + |
| 11 | +3. We need to change webpack [target](https://webpack.js.org/concepts/targets/) to Node.js. This allows webpack to handle dynamic imports in a Node-appropriate fashion, and also tells `vue-loader` to emit server-oriented code when compiling Vue components. |
| 12 | + |
| 13 | +4. When building a server entry, we would need to define an environment variable to indicate we are working with SSR. It might be helpful to add a few `scripts` to the project's `package.json`: |
| 14 | + |
| 15 | +```json |
| 16 | +"scripts": { |
| 17 | + "build:client": "vue-cli-service build --dest dist/client", |
| 18 | + "build:server": "SSR=1 vue-cli-service build --dest dist/server", |
| 19 | + "build": "npm run build:client && npm run build:server", |
| 20 | +} |
| 21 | +``` |
| 22 | + |
| 23 | +## Example Configuration |
| 24 | + |
| 25 | +Below is a sample `vue.config.js` that adds SSR rendering to a Vue CLI project, but it can be adapted for any webpack build. |
| 26 | + |
| 27 | +```js |
| 28 | +const { WebpackManifestPlugin } = require('webpack-manifest-plugin') |
| 29 | +const nodeExternals = require('webpack-node-externals') |
| 30 | +const webpack = require('webpack') |
| 31 | + |
| 32 | +module.exports = { |
| 33 | + chainWebpack: webpackConfig => { |
| 34 | + // We need to disable cache loader, otherwise the client build |
| 35 | + // will used cached components from the server build |
| 36 | + webpackConfig.module.rule('vue').uses.delete('cache-loader') |
| 37 | + webpackConfig.module.rule('js').uses.delete('cache-loader') |
| 38 | + webpackConfig.module.rule('ts').uses.delete('cache-loader') |
| 39 | + webpackConfig.module.rule('tsx').uses.delete('cache-loader') |
| 40 | + |
| 41 | + if (!process.env.SSR) { |
| 42 | + // Point entry to your app's client entry file |
| 43 | + webpackConfig |
| 44 | + .entry('app') |
| 45 | + .clear() |
| 46 | + .add('./src/entry-client.js') |
| 47 | + return |
| 48 | + } |
| 49 | + |
| 50 | + // Point entry to your app's server entry file |
| 51 | + webpackConfig |
| 52 | + .entry('app') |
| 53 | + .clear() |
| 54 | + .add('./src/entry-server.js') |
| 55 | + |
| 56 | + // This allows webpack to handle dynamic imports in a Node-appropriate |
| 57 | + // fashion, and also tells `vue-loader` to emit server-oriented code when |
| 58 | + // compiling Vue components. |
| 59 | + webpackConfig.target('node') |
| 60 | + // This tells the server bundle to use Node-style exports |
| 61 | + webpackConfig.output.libraryTarget('commonjs2') |
| 62 | + |
| 63 | + webpackConfig |
| 64 | + .plugin('manifest') |
| 65 | + .use(new WebpackManifestPlugin({ fileName: 'ssr-manifest.json' })) |
| 66 | + |
| 67 | + // https://webpack.js.org/configuration/externals/#function |
| 68 | + // https://github.com/liady/webpack-node-externals |
| 69 | + // Externalize app dependencies. This makes the server build much faster |
| 70 | + // and generates a smaller bundle file. |
| 71 | + |
| 72 | + // Do not externalize dependencies that need to be processed by webpack. |
| 73 | + // You should also whitelist deps that modify `global` (e.g. polyfills) |
| 74 | + webpackConfig.externals(nodeExternals({ allowlist: /\.(css|vue)$/ })) |
| 75 | + |
| 76 | + webpackConfig.optimization.splitChunks(false).minimize(false) |
| 77 | + |
| 78 | + webpackConfig.plugins.delete('preload') |
| 79 | + webpackConfig.plugins.delete('prefetch') |
| 80 | + webpackConfig.plugins.delete('progress') |
| 81 | + webpackConfig.plugins.delete('friendly-errors') |
| 82 | + |
| 83 | + webpackConfig.plugin('limit').use( |
| 84 | + new webpack.optimize.LimitChunkCountPlugin({ |
| 85 | + maxChunks: 1 |
| 86 | + }) |
| 87 | + ) |
| 88 | + } |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +## Externals Caveats |
| 93 | + |
| 94 | +Notice that in the `externals` option we are whitelisting CSS files. This is because CSS imported from dependencies should still be handled by webpack. If you are importing any other types of files that also rely on webpack (e.g. `*.vue`, `*.sass`), you should add them to the whitelist as well. |
| 95 | + |
| 96 | +If you are using `runInNewContext: 'once'` or `runInNewContext: true`, then you also need to whitelist polyfills that modify `global`, e.g. `babel-polyfill`. This is because when using the new context mode, **code inside a server bundle has its own `global` object.** Since you don't really need it on the server, it's actually easier to just import it in the client entry. |
| 97 | + |
| 98 | +## Generating `clientManifest` |
| 99 | + |
| 100 | +In addition to the server bundle, we can also generate a client build manifest. With the client manifest and the server bundle, the renderer now has information of both the server _and_ client builds. This way it can automatically infer and inject [preload / prefetch directives](https://css-tricks.com/prefetching-preloading-prebrowsing/), `<link>` and `<script>` tags into the rendered HTML. |
| 101 | + |
| 102 | +The benefits are two-fold: |
| 103 | + |
| 104 | +1. It can replace `html-webpack-plugin` for injecting the correct asset URLs when there are hashes in your generated filenames. |
| 105 | + |
| 106 | +2. When rendering a bundle that leverages webpack's on-demand code splitting features, we can ensure the optimal chunks are preloaded / prefetched, and also intelligently inject `<script>` tags for needed async chunks to avoid waterfall requests on the client, thus improving TTI (time-to-interactive). |
0 commit comments