API Reference
createRenderer
Create a Renderer
instance with (optional) options.
const { createRenderer } = require('vue-server-renderer')
const renderer = createRenderer({ /* options */ })
createBundleRenderer
Create a BundleRenderer
instance with a server bundle and (optional) options.
const { createBundleRenderer } = require('vue-server-renderer')
const renderer = createBundleRenderer(serverBundle, { /* options */ })
The serverBundle
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 webpack +
vue-server-renderer/server-plugin
.A string of JavaScript code (not recommended).
See Introducing the Server Bundle and Build Configuration for more details.
Class: Renderer
renderer.renderToString
Signature:
renderer.renderToString(vm, context?, callback?): ?Promise<string>
Render a Vue instance to string. The context object is optional. The callback is a typical Node.js style callback where the first argument is the error and the second argument is the rendered string.
In 2.5.0+, the callback is also optional. When no callback is passed, the method returns a Promise which resolves to the rendered HTML.
renderer.renderToStream
Signature:
renderer.renderToStream(vm[, context]): stream.Readable
Render a Vue instance to a Node.js readable stream (opens new window). The context object is optional. See Streaming for more details.
Class: BundleRenderer
bundleRenderer.renderToString
Signature:
bundleRenderer.renderToString([context, callback]): ?Promise<string>
Render the bundle to a string. The context object is optional. The callback is a typical Node.js style callback where the first argument is the error and the second argument is the rendered string.
In 2.5.0+, the callback is also optional. When no callback is passed, the method returns a Promise which resolves to the rendered HTML.
bundleRenderer.renderToStream
Signature:
bundleRenderer.renderToStream([context]): stream.Readable
Render the bundle to a Node.js readable stream (opens new window). The context object is optional. See Streaming for more details.
Renderer Options
template
- Type:
string
string | (() => string | Promise<string>)
(since 2.6)
If using a string template:
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.
The template also supports basic interpolation using the render context:
- Use double-mustache for HTML-escaped interpolation;
- Use triple-mustache for non-HTML-escaped interpolation.
The template automatically injects appropriate content when certain data is found on the render context:
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 this property will be automatically populated if usingvue-loader
+vue-style-loader
for component CSS.context.state
: (Object) initial Vuex store state that should be inlined in the page aswindow.__INITIAL_STATE__
. The inlined JSON is automatically sanitized with serialize-javascript (opens new window) to prevent XSS.In 2.5.0+, the embed script also self-removes in production mode.
In 2.6.0+, if
context.nonce
is present, it will be added as thenonce
attribute to the embedded script. This allows the inline script to conform to CSP that requires nonce.
In addition, when clientManifest
is also provided, the template automatically injects the following:
- Client-side JavaScript and CSS assets needed by the render (with async chunks automatically inferred);
- Optimal
<link rel="preload/prefetch">
resource hints for the rendered page.
You can disable all automatic injections by also passing inject: false
to the renderer.
If using a function template:
WARNING
Function template is only supported in 2.6+ and when using renderer.renderToString
. It is NOT supported in renderer.renderToStream
.
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.
The function receives two arguments:
- The rendering result of the app component as a string;
- The rendering context object.
Example:
const renderer = createRenderer({
template: (result, context) => {
return `<html>
<head>${context.head}</head>
<body>${result}</body>
<html>`
}
})
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).
See also:
clientManifest
Provide a client build manifest object generated by vue-server-renderer/client-plugin
. The client manifest provides the bundle renderer with the proper information for automatic asset injection into the HTML template. For more details, see Generating clientManifest.
inject
Controls whether to perform automatic injections when using template
. Defaults to true
.
See also: Manual Asset Injection.
shouldPreload
A function to control what files should have <link rel="preload">
resource hints generated.
By default, only JavaScript and CSS files will be preloaded, as they are absolutely needed for your application to boot.
For other types of assets such as images or fonts, preloading too much may waste bandwidth and even hurt performance, so what to preload will be scenario-dependent. You can control precisely what to preload using the shouldPreload
option:
const renderer = createBundleRenderer(bundle, {
template,
clientManifest,
shouldPreload: (file, type) => {
// type is inferred based on the file extension.
// https://fetch.spec.whatwg.org/#concept-request-destination
if (type === 'script' || type === 'style') {
return true
}
if (type === 'font') {
// only preload woff2 fonts
return /\.woff2$/.test(file)
}
if (type === 'image') {
// only preload important images
return file === 'hero.jpg'
}
}
})
shouldPrefetch
- 2.5.0+
A function to control what files should have <link rel="prefetch">
resource hints generated.
By default, all assets in async chunks will be prefetched since this is a low-priority directive; however you can customize what to prefetch in order to better control bandwidth usage. This option expects the same function signature as shouldPreload
.
runInNewContext
- 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, the app code is isolated from the server process and we don't need to worry about the stateful singleton problem 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
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:
- Dependencies that modifies
global
(e.g. polyfills) cannot be externalized in this mode; - 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
basedir
- only used in
createBundleRenderer
Explicitly declare the base directory for the server bundle to resolve node_modules
dependencies from. This is only needed if your generated bundle file is placed in a different location from where the externalized NPM dependencies are installed, or your vue-server-renderer
is NPM-linked into your current project.
cache
Provide a component cache implementation. The cache object must implement the following interface (using Flow notations):
type RenderCache = {
get: (key: string, cb?: Function) => string | void;
set: (key: string, val: string) => void;
has?: (key: string, cb?: Function) => boolean | void;
};
A typical usage is passing in an lru-cache (opens new window):
const LRU = require('lru-cache')
const renderer = createRenderer({
cache: LRU({
max: 10000
})
})
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:
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)
}
}
})
directives
Allows you to provide server-side implementations for your custom directives:
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 (opens new window).
serializer
New in 2.6
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 (opens new window) 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.
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.
webpack Plugins
The webpack plugins are provided as standalone files and should be required directly:
const VueSSRServerPlugin = require('vue-server-renderer/server-plugin')
const VueSSRClientPlugin = require('vue-server-renderer/client-plugin')
The default files generated are:
vue-ssr-server-bundle.json
for the server plugin;vue-ssr-client-manifest.json
for the client plugin.
The filenames can be customized when creating the plugin instances:
const plugin = new VueSSRServerPlugin({
filename: 'my-server-bundle.json'
})
See Build Configuration for more information.