API Reference
+createRenderer([options])
+Create a Renderer instance with (optional) options.
const { createRenderer } = require('vue-server-renderer')
+const renderer = createRenderer({ ... })
+createBundleRenderer(bundle[, options])
+Create a BundleRenderer instance with a server bundle and (optional) options.
const { createBundleRenderer } = require('vue-server-renderer')
+const renderer = createBundleRenderer(serverBundle, { ... })
+The serverBundle argument can be one of the following:
-
+
An absolute path to generated bundle file (
+.jsor.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(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(vm[, context]): stream.ReadableRender a Vue instance to a Node.js readable stream. The context object is optional. See Streaming for more details.
+
+
Class: BundleRenderer
+-
+
+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([context]): stream.ReadableRender the bundle to a Node.js readable stream. The context object is optional. See Streaming for more details.
+
+
Renderer Options
+-
+
+templateProvide 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-loaderfor 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 to prevent XSS.In 2.5.0+, the embed script also self-removes in production mode.
+
+
In addition, when
+clientManifestis 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: falseto the renderer.See also:
+ +
+
+clientManifest-
+
- 2.3.0+ +
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-
+
- 2.3.0+ +
Controls whether to perform automatic injections when using
+template. Defaults totrue.See also: Manual Asset Injection.
+
+
+shouldPreload-
+
- 2.3.0+ +
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
+shouldPreloadoption: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-
+
- 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, 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
+truefor backwards compatibility, but it is recommended to userunInNewContext: falseorrunInNewContext: 'once'whenever you can.+
+In 2.3.0 this option has a bug where
+runInNewContext: falsestill 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 sameglobalcontext with the server process, so be careful about code that modifiesglobalin your application code.With
+runInNewContext: 'once'(2.3.1+), the bundle is evaluated in a separateglobalcontext, however only once at startup. This provides better app code isolation since it prevents the bundle from accidentally polluting the server process'globalobject. 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
Errorin the server process.
+
See also: Source Code Structure
+
+
+basedir-
+
- 2.2.0+ +
- only used in
createBundleRenderer
+
Explicitly declare the base directory for the server bundle to resolve
+node_modulesdependencies 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 yourvue-server-rendereris NPM-linked into your current project.
+
+cacheProvide 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:
+const LRU = require('lru-cache') + +const renderer = createRenderer({ + cache: LRU({ + max: 10000 + }) +}) +Note that the cache object should at least implement
+getandset. In addition,getandhascan 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) + } + } +}) +
+
+directivesAllows 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.
+
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.jsonfor the server plugin;
+vue-ssr-client-manifest.jsonfor 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.
+ + +