Skip to content

Commit 31b2b69

Browse files
yyx990803yyx990803
authored
2.6 updates (#222)
* 2.6: serverCacheKey bail out * 2.6: api additions * docs: use ssrPrefetch in data guide (#214) * 2.6: serverPrefetch updates
1 parent 918ef98 commit 31b2b69

File tree

3 files changed

+169
-136
lines changed

3 files changed

+169
-136
lines changed

Diff for: ‎docs/api/README.md

+62
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,12 @@ Render the bundle to a [Node.js readable stream](https://nodejs.org/dist/latest-
8484
8585
### template
8686
87+
- **Type:**
88+
- `string`
89+
- `string | (() => string | Promise<string>)` (since 2.6)
90+
91+
**If using a string template:**
92+
8793
Provide a template for the entire page's HTML. The template should contain a comment `<!--vue-ssr-outlet-->` which serves as the placeholder for rendered app content.
8894
8995
The template also supports basic interpolation using the render context:
@@ -101,13 +107,43 @@ The template automatically injects appropriate content when certain data is foun
101107
102108
In 2.5.0+, the embed script also self-removes in production mode.
103109
110+
In 2.6.0+, if `context.nonce` is present, it will be added as the `nonce` attribute to the embedded script. This allows the inline script to conform to CSP that requires nonce.
111+
104112
In addition, when `clientManifest` is also provided, the template automatically injects the following:
105113
106114
- Client-side JavaScript and CSS assets needed by the render (with async chunks automatically inferred);
107115
- Optimal `<link rel="preload/prefetch">` resource hints for the rendered page.
108116
109117
You can disable all automatic injections by also passing `inject: false` to the renderer.
110118
119+
**If using a function template:**
120+
121+
::: warning
122+
Function template is only supported in 2.6+ and when using `renderer.renderToString`. It is NOT supported in `renderer.renderToStream`.
123+
:::
124+
125+
The `template` option can also be function that returns the rendered HTML or a Promise that resolves to the rendered HTML. This allows you to leverage native JavaScript template strings and potential async operations in the template rendering process.
126+
127+
The function receives two arguments:
128+
129+
1. The rendering result of the app component as a string;
130+
2. The rendering context object.
131+
132+
Example:
133+
134+
``` js
135+
const renderer = createRenderer({
136+
template: (result, context) => {
137+
return `<html>
138+
<head>${context.head}</head>
139+
<body>${result}</body>
140+
<html>`
141+
}
142+
})
143+
```
144+
145+
Note that when using a custom template function, nothing will be automatically injected - you will be in full control of what the eventual HTML includes, but also will be responsible for including everything yourself (e.g. asset links if you are using the bundle renderer).
146+
111147
See also:
112148
113149
- [Using a Page Template](../guide/#using-a-page-template)
@@ -245,6 +281,32 @@ const renderer = createRenderer({
245281
246282
As an example, check out [`v-show`'s server-side implementation](https://github.com/vuejs/vue/blob/dev/src/platforms/web/server/directives/show.js).
247283
284+
### serializer
285+
286+
> New in 2.6
287+
288+
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 }`.
289+
290+
## Server-only Component Options
291+
292+
### serverCacheKey
293+
294+
- **Type:** `(props) => any`
295+
296+
Return the cache key for the component based on incoming props. Does NOT have access to `this`.
297+
298+
Since 2.6, you can explicitly bail out of caching by returning `false`.
299+
300+
See more details in [Component-level Caching](../guide/caching.html#component-level-caching).
301+
302+
### serverPrefetch
303+
304+
- **Type:** `() => Promise<any>`
305+
306+
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`.
307+
308+
See more details in [Data Fetching](../guide/data.html).
309+
248310
## webpack Plugins
249311
250312
The webpack plugins are provided as standalone files and should be required directly:

Diff for: ‎docs/guide/caching.md

+4
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,10 @@ The key returned from `serverCacheKey` should contain sufficient information to
7373

7474
Returning a constant will cause the component to always be cached, which is good for purely static components.
7575

76+
::: tip Bailing out from Caching
77+
Since 2.6.0, explicitly returning `false` in `serverCacheKey` will cause the component to bail out of caching and be rendered afresh.
78+
:::
79+
7680
### When to use component caching
7781

7882
If the renderer hits a cache for a component during render, it will directly reuse the cached result for the entire sub tree. This means you should **NOT** cache a component when:

0 commit comments

Comments
 (0)