document runInNewContext changes in 2.3.1

Author: yyx990803

en/api.md

@@ -130,10 +130,20 @@ See [Introducing the Server Bundle](./bundle-renderer.md) and [Build Configurati
 
   - 2.3.0+
   - only used in `createBundleRenderer`
+  - Expects: `boolean | 'once'` (`'once'` only supported in 2.3.1+)
 
-  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, the app code is isolated from the server process and we don't need to worry about the [stateful singleton problem](./structure.md#avoid-stateful-singletons) mentioned in the docs. However, this mode comes at some considerable performance cost because re-executing the bundle is expensive especially when the app gets bigger.
 
-  This option defaults to `true` for backwards compatibility, but it is recommended to use `runInNewContext: false` whenever you can.
+  This option defaults to `true` for backwards compatibility, but it is recommended to use `runInNewContext: false` or `runInNewContext: 'once'` whenever you can.
+
+  > In 2.3.0 this option has a bug where `runInNewContext: false` still executes the bundle using a separate global context. The following information assumes version 2.3.1+.
+
+  With `runInNewContext: false`, the bundle code will run in the same `global` context with the server process, so be careful about code that modifies `global` in your application code.
+
+  With `runInNewContext: 'once'` (2.3.1+), the bundle is evaluated in a separate `global` context, however only once at startup. This provides better app code isolation since it prevents the bundle from accidentally polluting the server process' `global` object. The caveats are that:
+
+  1. Dependencies that modifies `global` (e.g. polyfills) cannot be externalized in this mode;
+  2. Values returned from the bundle execution will be using different global constructors, e.g. an error caught inside the bundle will not be an instance of `Error` in the server process.
 
   See also: [Source Code Structure](./structure.md)
 

en/build-config.md

@@ -64,7 +64,7 @@ Alternatively, you can also pass the bundle as an Object to `createBundleRendere
 
 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.
+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 when using Node 7.6+, it's actually easier to just import it in the client entry.
 
 ## Client Config
 

en/bundle-renderer.md

@@ -49,12 +49,4 @@ server.get('*', (req, res) => {
 
 When `renderToString` is called on a bundle renderer, it will automatically execute the function exported by the bundle to create an app instance (passing `context` as the argument) , and then render it.
 
----
-
-### 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 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.
+Note it's recommended to set the `runInNewContext` option to `false` or `'once'`. See its [API reference](./api.md#runinnewcontext) for more details.