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  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 using vue-loader + vue-style-loader for component CSS.
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 (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 the nonce 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).

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.

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.

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.

# API Reference

# createRenderer

# createBundleRenderer

# Class: Renderer

# renderer.renderToString

# renderer.renderToStream

# Class: BundleRenderer

# bundleRenderer.renderToString

# bundleRenderer.renderToStream

# Renderer Options

# template

# clientManifest

# inject

# shouldPreload

# shouldPrefetch

# runInNewContext

# basedir

# cache

# directives

# serializer

# Server-only Component Options

# serverCacheKey

# serverPrefetch

# webpack Plugins

API Reference

createRenderer

createBundleRenderer

Class: Renderer

renderer.renderToString

renderer.renderToStream

Class: BundleRenderer

bundleRenderer.renderToString

bundleRenderer.renderToStream

Renderer Options

template

clientManifest

inject

shouldPreload

shouldPrefetch

runInNewContext

basedir

cache

directives

serializer

Server-only Component Options

serverCacheKey

serverPrefetch

webpack Plugins