2.6: serverPrefetch updates

Author: yyx990803

docs/api/README.md

@@ -287,6 +287,26 @@ As an example, check out [`v-show`'s server-side implementation](https://github.
 
 Provide a custom serializer function for `context.state`. Since the serialized state will be part of your final HTML, it is important to use a function that properly escapes HTML characters for security reasons. The default serializer is [serialize-javascript](https://github.com/yahoo/serialize-javascript) with `{ isJSON: true }`.
 
+## Server-only Component Options
+
+### serverCacheKey
+
+- **Type:** `(props) => any`
+
+  Return the cache key for the component based on incoming props. Does NOT have access to `this`.
+
+  Since 2.6, you can explicitly bail out of caching by returning `false`.
+
+  See more details in [Component-level Caching](../guide/caching.html#component-level-caching).
+
+### serverPrefetch
+
+- **Type:** `() => Promise<any>`
+
+  Fetch async data during server side rendering. It should store fetched data into a global store and return a Promise. The server renderer will wait on this hook until the Promise is resolved. This hook has access to the component instance via `this`.
+
+  See more details in [Data Fetching](../guide/data.html).
+
 ## webpack Plugins
 
 The webpack plugins are provided as standalone files and should be required directly:

docs/guide/data.md

@@ -87,13 +87,13 @@ So, where do we place the code that dispatches the data-fetching actions?
 
 The data we need to fetch is determined by the route visited - which also determines what components are rendered. In fact, the data needed for a given route is also the data needed by the components rendered at that route. So it would be natural to place the data fetching logic inside route components.
 
-We will use the `ssrPrefetch` option in our components. This option is recognized by the server renderer and will be pause the component render until the promise it returns is resolved. Since the component instance is already created at this point, it has access to `this`.
+We will use the `serverPrefetch` option (new in 2.6.0+) in our components. This option is recognized by the server renderer and will pause the rendering until the promise it returns is resolved. This allows us to "wait" on async data during the rendering process.
 
 ::: tip
-You can use `ssrPrefetch` in any component, not just the route-level components.
+You can use `serverPrefetch` in any component, not just the route-level components.
 :::
 
-Here is an example `Item.vue` component that is rendered at the `'/item/:id'` route:
+Here is an example `Item.vue` component that is rendered at the `'/item/:id'` route. Since the component instance is already created at this point, it has access to `this`:
 
 ``` html
 <!-- Item.vue -->
@@ -113,7 +113,7 @@ export default {
 
   // Server-side only
   // This will be called by the server renderer automatically
-  ssrPrefetch () {
+  serverPrefetch () {
     // return the Promise from the action
     // so that the component waits before rendering
     return this.fetchItem()
@@ -142,9 +142,13 @@ export default {
 You should check if the component was server-side rendered in the `mounted` hook to avoid executing the logic twice.
 :::
 
-## Server Data Fetching
+::: tip
+You may find the same `fetchItem()` logic repeated multiple times (in `serverPrefetch`, `mounted` and `watch` callbacks) in each component - it is recommended to create your own abstraction (e.g. a mixin or a plugin) to simplify such code.
+:::
 
-In `entry-server.js`, we will set the store state in the render context after the app is finished rendering, thanks to the `context.rendered` hook recognized by the server renderer.
+## Final State Injection
+
+Now we know that the rendering process will wait for data fetching in our components, how do we know when it is "done"? In order to do that, we need to attach a `rendered` callback to the render context (also new in 2.6), which the server renderer will call when the entire rendering process is finished. At this moment, the store should have been filled with the final state. We can then inject it on to the context in that callback:
 
 ``` js
 // entry-server.js
@@ -233,7 +237,7 @@ export default {
   },
 
   // Server-side only
-  ssrPrefetch () {
+  serverPrefetch () {
     this.registerFoo()
     return this.fooInc()
   },
@@ -243,7 +247,7 @@ export default {
     // We already incremented 'count' on the server
     // We know by checking if the 'foo' state already exists
     const alreadyIncremented = !!this.$store.state.foo
-    
+
     // We register the foo module
     this.registerFoo()