vue/packages/vue-server-renderer/README.md

478 lines
20 KiB
Markdown
Raw Normal View History

2016-06-11 07:38:58 +08:00
# vue-server-renderer
2017-04-22 22:20:21 +08:00
> This package is auto-generated. For pull requests please see [src/entries/web-server-renderer.js](https://github.com/vuejs/vue/blob/dev/src/platforms/web/server-renderer.js).
2016-06-11 07:38:58 +08:00
2016-06-28 13:10:19 +08:00
This package offers Node.js server-side rendering for Vue 2.0.
- [Installation](#installation)
- [API](#api)
- [Renderer Options](#renderer-options)
- [Why Use `bundleRenderer`?](#why-use-bundlerenderer)
- [Creating the Server Bundle](#creating-the-server-bundle)
2017-03-31 11:03:43 +08:00
- [Creating the Client Manifest](#creating-the-client-manifest)
- [Component Caching](#component-caching)
- [Client Side Hydration](#client-side-hydration)
2016-06-28 13:10:19 +08:00
## Installation
``` bash
npm install vue-server-renderer
```
## API
2016-06-28 14:48:27 +08:00
### createRenderer([[rendererOptions](#renderer-options)])
2016-06-28 13:10:19 +08:00
Create a `renderer` instance.
``` js
2016-06-28 14:48:27 +08:00
const renderer = require('vue-server-renderer').createRenderer()
2016-06-28 13:10:19 +08:00
```
---
### renderer.renderToString(vm, cb)
Render a Vue instance to string. The callback is a standard Node.js callback that receives the error as the first argument:
``` js
const Vue = require('vue')
2016-06-28 14:48:27 +08:00
const renderer = require('vue-server-renderer').createRenderer()
2016-06-28 13:10:19 +08:00
const vm = new Vue({
render (h) {
return h('div', 'hello')
}
})
renderer.renderToString(vm, (err, html) => {
console.log(html) // -> <div server-rendered="true">hello</div>
})
```
---
### renderer.renderToStream(vm)
Render a Vue instance in streaming mode. Returns a Node.js readable stream.
``` js
// example usage with express
app.get('/', (req, res) => {
const vm = new App({ url: req.url })
const stream = renderer.renderToStream(vm)
res.write(`<!DOCTYPE html><html><head><title>...</title></head><body>`)
stream.on('data', chunk => {
res.write(chunk)
})
stream.on('end', () => {
res.end('</body></html>')
})
})
```
---
### createBundleRenderer(bundle, [[rendererOptions](#renderer-options)])
2016-06-28 13:10:19 +08:00
Creates a `bundleRenderer` instance using pre-compiled application bundle. The `bundle` argument can be one of the following:
- An absolute path to generated bundle file (`.js` or `.json`). Must start with `/` to be treated as a file path.
- A bundle object generated by `vue-ssr-webpack-plugin`.
- A string of JavaScript code.
See [Creating the Server Bundle](#creating-the-server-bundle) for more details.
For each render call, the code will be re-run in a new context using Node.js' `vm` module. This ensures your application state is discrete between requests, and you don't need to worry about structuring your application in a limiting pattern just for the sake of SSR.
2016-06-28 13:10:19 +08:00
``` js
const createBundleRenderer = require('vue-server-renderer').createBundleRenderer
// absolute filepath
let renderer = createBundleRenderer('/path/to/bundle.json')
// bundle object
let renderer = createBundleRenderer({ ... })
// code (not recommended for lack of source map support)
let renderer = createBundleRenderer(bundledCode)
2016-06-28 13:10:19 +08:00
```
---
### bundleRenderer.renderToString([context], cb)
Render the bundled app to a string. Same callback interface with `renderer.renderToString`. The optional context object will be passed to the bundle's exported function.
``` js
bundleRenderer.renderToString({ url: '/' }, (err, html) => {
// ...
})
```
---
### bundleRenderer.renderToStream([context])
Render the bundled app to a stream. Same stream interface with `renderer.renderToStream`. The optional context object will be passed to the bundle's exported function.
``` js
bundleRenderer
.renderToStream({ url: '/' })
.pipe(writableStream)
```
## Renderer Options
### cache
Provide a [component cache](#component-caching) implementation. The cache object must implement the following interface (using Flow notations):
2016-06-28 13:10:19 +08:00
``` js
type RenderCache = {
get: (key: string, cb?: Function) => string | void;
set: (key: string, val: string) => void;
has?: (key: string, cb?: Function) => boolean | void;
};
2016-06-30 04:50:21 +08:00
```
A typical usage is passing in an [lru-cache](https://github.com/isaacs/node-lru-cache):
``` js
const LRU = require('lru-cache')
2016-06-28 13:10:19 +08:00
const renderer = createRenderer({
2016-06-30 04:50:21 +08:00
cache: LRU({
2016-06-28 13:10:19 +08:00
max: 10000
2016-06-30 04:50:21 +08:00
})
2016-06-28 13:10:19 +08:00
})
```
2016-07-08 04:35:24 +08:00
Note that the cache object should at least implement `get` and `set`. In addition, `get` and `has` can be optionally async if they accept a second argument as callback. This allows the cache to make use of async APIs, e.g. a redis client:
``` js
const renderer = createRenderer({
cache: {
get: (key, cb) => {
redisClient.get(key, (err, res) => {
// handle error if any
cb(res)
})
},
set: (key, val) => {
redisClient.set(key, val)
}
}
})
```
---
### template
> New in 2.2.0
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.
In addition, when both a template and a render context is provided (e.g. when using the `bundleRenderer`), the renderer will also automatically inject the following properties found on the render context:
2017-02-14 03:46:54 +08:00
- `context.head`: (string) any head markup that should be injected into the head of the page.
- `context.styles`: (string) any inline CSS that should be injected into the head of the page. Note that `vue-loader` 10.2.0+ (which uses `vue-style-loader` 2.0) will automatically populate this property with styles used in rendered components.
- `context.state`: (Object) initial Vuex store state that should be inlined in the page as `window.__INITIAL_STATE__`. The inlined JSON is automatically sanitized with [serialize-javascript](https://github.com/yahoo/serialize-javascript).
**Example:**
``` js
const renderer = createRenderer({
template:
'<!DOCTYPE html>' +
'<html lang="en">' +
'<head>' +
'<meta charset="utf-8">' +
// context.head will be injected here
// context.styles will be injected here
'</head>' +
'<body>' +
'<!--vue-ssr-outlet-->' + // <- app content rendered here
// context.state will be injected here
'</body>' +
'</html>'
})
```
---
### basedir
> New in 2.2.0
2017-03-31 11:03:43 +08:00
- only used in `createBundleRenderer`
Explicitly declare the base directory for the server bundle to resolve node_modules from. This is only needed if your generated bundle file is placed in a different location from where the externalized NPM dependencies are installed.
Note that the `basedir` is automatically inferred if you use `vue-ssr-webpack-plugin` or provide an absolute path to `createBundleRenderer` as the first argument, so in most cases you don't need to provide this option. However, this option does allow you to explicitly overwrite the inferred value.
---
2017-03-31 11:03:43 +08:00
### clientManifest
> New in 2.3.0
- only used in `createBundleRenderer`
- only used when the `template` option is also provided
Provide a client build manifest object generated by `vue-ssr-webpack-plugin`. With the client manifest, the `bundleRenderer` has webpack build information of both the server and client, and thus will be able to automatically infer and inject asset links into the rendered HTML. For more details, see [Creating the Client Manifest](#creating-the-client-manifest).
---
### shouldPreload
> New in 2.3.0
- only used in `createBundleRenderer`
- only used when the `template` and `clientManifest` options are also provided
2017-03-31 17:42:56 +08:00
When a client manifest is present, the renderer will automatically inject [preload and prefetch directives](https://medium.com/reloading/preload-prefetch-and-priorities-in-chrome-776165961bbf) into the `<head>` section.
2017-03-31 11:03:43 +08:00
2017-03-31 17:42:56 +08:00
By default, only JavaScript chunks used during the server-side render will be preloaded, as they are absolutely needed for your application to boot.
2017-03-31 11:03:43 +08:00
2017-03-31 17:42:56 +08:00
For other types of assets such as images or fonts, how much and what to preload will be scenario-dependent. You can control precisely what to preload using the `shouldPreload` option:
2017-03-31 11:03:43 +08:00
``` js
const renderer = createBundleRenderer(serverBundle, {
template,
clientManifest,
shouldPreload: (file, type) => {
// type is inferred based on the file extension.
// https://fetch.spec.whatwg.org/#concept-request-destination
2017-03-31 17:42:56 +08:00
if (type === 'script') {
2017-03-31 11:03:43 +08:00
return true
}
2017-03-31 17:42:56 +08:00
if (type === 'font') {
// only preload woff2 fonts
return /\.woff2$/.test(file)
}
2017-03-31 11:03:43 +08:00
if (type === 'image') {
// only preload important images
return file === 'hero.jpg'
}
}
})
```
---
### directives
Allows you to provide server-side implementations for your custom directives:
``` js
const renderer = createRenderer({
directives: {
example (vnode, directiveMeta) {
// transform vnode based on directive binding metadata
}
}
})
```
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).
## Why Use `bundleRenderer`?
2017-02-14 03:46:54 +08:00
When we bundle our front-end code with a module bundler such as webpack, it can introduce some complexity when we want to reuse the same code on the server. For example, if we use `vue-loader`, TypeScript or JSX, the code cannot run natively in Node. Our code may also rely on some webpack-specific features such as file handling with `file-loader` or style injection with `style-loader`, both of which can be problematic when running inside a native Node module environment.
2017-02-14 03:46:54 +08:00
The most straightforward solution to this is to leverage webpack's `target: 'node'` feature and simply use webpack to bundle our code on both the client AND the server.
Having a compiled server bundle also provides another advantage in terms of code organization. In a typical Node.js app, the server is a long-running process. If we run our application modules directly, the instantiated modules will be shared across every request. This imposes some inconvenient restrictions to the application structure: we will have to avoid any use of global stateful singletons (e.g. the store), otherwise state mutations caused by one request will affect the result of the next.
Instead, it's more straightforward to run our app "fresh", in a sandboxed context for each request, so that we don't have to think about avoiding state contamination across requests.
## Creating the Server Bundle
2016-08-12 07:13:16 +08:00
<img width="973" alt="screen shot 2016-08-11 at 6 06 57 pm" src="https://cloud.githubusercontent.com/assets/499550/17607895/786a415a-5fee-11e6-9c11-45a2cfdf085c.png">
The application bundle can be either a string of bundled code (not recommended due to lack of source map support), or a special object of the following type:
2017-02-02 02:50:12 +08:00
``` js
type RenderBundle = {
entry: string; // name of the entry file
files: { [filename: string]: string; }; // all files in the bundle
maps: { [filename: string]: string; }; // source maps
}
```
Although theoretically you can use any build tool to generate the bundle, it is recommended to use webpack + `vue-loader` + [vue-ssr-webpack-plugin](https://github.com/vuejs/vue-ssr-webpack-plugin) for this purpose. The plugin will automatically turn the build output into a single JSON file that you can then pass to `createBundleRenderer`. This setup works seamlessly even if you use webpack's on-demand code splitting features such as dynamic `import()`.
2017-02-14 03:46:54 +08:00
The typical workflow is setting up a base webpack configuration file for the client-side, then modify it to generate the server-side bundle with the following changes:
2017-02-02 02:50:12 +08:00
1. Set `target: 'node'` and `output: { libraryTarget: 'commonjs2' }` in your webpack config.
2. Add [vue-ssr-webpack-plugin](https://github.com/vuejs/vue-ssr-webpack-plugin) to your webpack plugins. This plugin automatically generates the bundle as a single JSON file which contains all the files and source maps of the entire bundle. This is particularly important if you use Webpack's code-splitting features that result in a multi-file bundle.
3. In your server-side entry point, export a function. The function will receive the render context object (passed to `bundleRenderer.renderToString` or `bundleRenderer.renderToStream`), and should return a Promise, which should eventually resolve to the app's root Vue instance:
``` js
// server-entry.js
import Vue from 'vue'
import App from './App.vue'
const app = new Vue(App)
// the default export should be a function
// which will receive the context of the render call
export default context => {
// data pre-fetching
return app.fetchServerData(context.url).then(() => {
return app
})
}
```
2017-02-02 02:50:12 +08:00
4. It's also a good idea to externalize your dependencies (see below).
### Externals
When using the `bundleRenderer`, we will by default bundle every dependency of our app into the server bundle as well. This means on each request these depdencies will need to be parsed and evaluated again, which is unnecessary in most cases.
We can optimize this by externalizing dependencies from your bundle. During the render, any raw `require()` calls found in the bundle will return the actual Node module from your rendering process. With Webpack, we can simply list the modules we want to externalize using the [`externals` config option](https://webpack.github.io/docs/configuration.html#externals):
``` js
// webpack.config.js
module.exports = {
// this will externalize all modules listed under "dependencies"
// in your package.json
externals: Object.keys(require('./package.json').dependencies)
}
```
### Externals Caveats
Since externalized modules will be shared across every request, you need to make sure that the dependency is **idempotent**. That is, using it across different requests should always yield the same result - it cannot have global state that may be changed by your application. Interactions between externalized modules are fine (e.g. using a Vue plugin).
2017-03-31 11:03:43 +08:00
## Creating the Client Manifest
`vue-server-renderer` 2.2 supports rendering the entire HTML page with the `template` option. 2.3 introduces another new feature, which allows us to pass a manifest of our client-side build to the `bundleRenderer`. This provides the renderer with information of both the server AND client builds, so it can automatically infer and inject preload / prefetch directives and script tags into the rendered HTML. This is particularly useful when rendering a bundle that leverages webpack's on-demand code splitting features: we can ensure the right chunks are preloaded / prefetched, and also directly embed `<script>` tags for needed async chunks in the HTML to avoid waterfall requests on the client, thus improving TTI (time-to-interactive).
To generate a client manifest, you need to add the client plugin to your client webpack config. In addition:
- Make sure to use `CommonsChunkPlugin` to split the webpack runtime into its own entry chunk, so that async chunks can be injected **after** the runtime and **before** your main app code.
- Since in this case `vue-server-renderer` will be dynamically injecting the asset links, you don't need to use `html-webpack-plugin`. However, the setup only handles JavaScript. If you want to use `html-webpack-plugin` for embedding other types of assets (e.g fonts), you can still use it - just make sure to configure it with `inject: false` so that it doesn't duplicate-inject the scripts.
``` js
// in your webpack client bundle config
const webpack = require('webpack')
const { VueSSRClientPlugin } = require('vue-ssr-webpack-plugin')
module.exports = {
// ...
plugins: [
// this splits the webpack runtime into a leading chunk
// so that async chunks can be injected right after it.
// this also enables better caching for your app/vendor code.
new webpack.optimize.CommonsChunkPlugin({
name: 'manifest',
minChunks: Infinity
}),
// this will generate the client manifest JSON file.
new VueSSRClientPlugin()
]
}
```
This will generate an additional `vue-ssr-client-manifest.json` file in your build output. Simply require and pass it to the `bundleRenderer`:
``` js
const { createBundleRenderer } = require('vue-server-renderer')
const template = require('fs').readFileSync('/path/to/template.html', 'utf-8')
const serverBundle = require('/path/to/vue-ssr-bundle.json')
const clientManifest = require('/path/to/vue-ssr-client-manifest.json')
const renderer = createBundleRenderer(serverBundle, {
template,
clientManifest
})
```
With this setup, your server-rendered HTML for a build with code-splitting will look something like this:
``` html
<html><head>
<!-- chunks used for this render should have preload -->
<link rel="preload" href="/manifest.js" as="script">
<link rel="preload" href="/main.js" as="script">
<link rel="preload" href="/0.js" as="script">
<!-- unused async chunks should have prefetch -->
<link rel="prefetch" href="/1.js" as="script">
</head><body>
<div data-server-rendered="true"><div>async</div></div>
<!-- manifest chunk should be first -->
<script src="/manifest.js"></script>
<!-- async chunks should be before main chunk -->
<script src="/0.js"></script>
<script src="/main.js"></script>
</body></html>`
```
You can also control precisely what to preload with the [shouldPreload](#shouldpreload) option.
## Component Caching
2016-06-28 13:10:19 +08:00
2016-07-02 21:49:51 +08:00
You can easily cache components during SSR by implementing the `serverCacheKey` function:
2016-06-28 13:10:19 +08:00
``` js
export default {
name: 'item', // required
2016-06-28 13:10:19 +08:00
props: ['item'],
2016-07-02 21:49:51 +08:00
serverCacheKey: props => props.item.id,
2016-06-28 13:10:19 +08:00
render (h) {
return h('div', this.item.id)
}
}
```
Note that cachable component **must also define a unique "name" option**. This is necessary for Vue to determine the identity of the component when using the
bundle renderer.
With a unique name, the cache key is thus per-component: you don't need to worry about two components returning the same key. A cache key should contain sufficient information to represent the shape of the render result. The above is a good implementation if the render result is solely determined by `props.item.id`. However, if the item with the same id may change over time, or if render result also relies on another prop, then you need to modify your `getCacheKey` implementation to take those other variables into account.
2016-06-28 13:10:19 +08:00
Returning a constant will cause the component to always be cached, which is good for purely static components.
### When to use component caching
2016-06-28 13:10:19 +08:00
If the renderer hits a cache for a component during render, it will directly reuse the cached result for the entire sub tree. So **do not cache a component containing child components that rely on global state**.
In most cases, you shouldn't and don't need to cache single-instance components. The most common type of components that need caching are ones in big lists. Since these components are usually driven by objects in database collections, they can make use of a simple caching strategy: generate their cache keys using their unique id plus the last updated timestamp:
``` js
2016-07-02 21:49:51 +08:00
serverCacheKey: props => props.item.id + '::' + props.item.last_updated
2016-06-28 13:10:19 +08:00
```
## Client Side Hydration
In server-rendered output, the root element will have the `server-rendered="true"` attribute. On the client, when you mount a Vue instance to an element with this attribute, it will attempt to "hydrate" the existing DOM instead of creating new DOM nodes.
In development mode, Vue will assert the client-side generated virtual DOM tree matches the DOM structure rendered from the server. If there is a mismatch, it will bail hydration, discard existing DOM and render from scratch. **In production mode, this assertion is disabled for maximum performance.**
### Hydration Caveats
One thing to be aware of when using SSR + client hydration is some special HTML structures that may be altered by the browser. For example, when you write this in a Vue template:
``` html
<table>
<tr><td>hi</td></tr>
</table>
```
The browser will automatically inject `<tbody>` inside `<table>`, however, the virtual DOM generated by Vue does not contain `<tbody>`, so it will cause a mismatch. To ensure correct matching, make sure to write valid HTML in your templates.