diff --git a/en/build-config.md b/en/build-config.md index d857c107..740e0dfb 100644 --- a/en/build-config.md +++ b/en/build-config.md @@ -36,6 +36,7 @@ module.exports = merge(baseConfig, { externals: nodeExternals({ // do not externalize dependencies that need to be processed by webpack. // you can add more file types here e.g. raw *.vue files + // you should also whitelist deps that modifies `global` (e.g. polyfills) whitelist: /\.css$/ }), @@ -59,6 +60,12 @@ const renderer = createBundleRenderer('/path/to/vue-ssr-server-bundle.json', { Alternatively, you can also pass the bundle as an Object to `createBundleRenderer`. This is useful for hot-reload during development - see the HackerNews demo for a [reference setup](https://github.com/vuejs/vue-hackernews-2.0/blob/master/build/setup-dev-server.js). +### Externals Caveats + +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. + +Another type of modules to whitelist are polyfills that modify `global`, e.g. `babel-polyfill`. This is because **code inside a server bundle has its own `global` object.** Since you don't really need it on the server when using Node 7.6+, it's actually easier to just import it in the client entry. + ## Client Config The client config can remain largely the same with the base config. Obviously you need to point `entry` to your client entry file. Aside from that, if you are using `CommonsChunkPlugin`, make sure to use it only in the client config because the server bundle requires a single entry chunk. diff --git a/en/bundle-renderer.md b/en/bundle-renderer.md index d354eb29..3c0b7cae 100644 --- a/en/bundle-renderer.md +++ b/en/bundle-renderer.md @@ -53,6 +53,8 @@ When `rendertoString` is called on a bundle renderer, it will automatically exec ### The `runInNewContext` Option -By default, for each render the bundle renderer will create a fresh V8 context and re-execute the entire bundle. This has some benefits - for example, we don't need to worry about the "stateful singleton" problem we mentioned earlier. However, this mode comes at some considerable performance cost because re-executing the bundle is expensive especially when the app gets bigger. +By default, for each render the bundle renderer will create a fresh V8 context and re-execute the entire bundle. This has some benefits - for example, we don't need to worry about the "stateful singleton" problem we mentioned earlier. However, this mode comes at some considerable performance cost because re-executing the entire bundle is expensive especially when the app gets bigger. In `vue-server-renderer >= 2.3.0`, this option still defaults to `true` for backwards compatibility, but it is recommended to use `runInNewContext: false` whenever you can. + +Note that when using `runInNewContext: false`, the bundle is still **evaluated in a separate `global` context**, however only once. This prevents the bundle accidentally polluting the server process' `global` object. The difference from the default behavior is that it will not create **new** contexts for each render call.