@vue/server-renderer

Note: as of 3.2.13+, this package is included as a dependency of the main vue package and can be accessed as vue/server-renderer. This means you no longer need to explicitly install this package and ensure its version match that of vue's. Just use the vue/server-renderer deep import instead.

Basic API

renderToString

Signature

1
2
3
4
function renderToString(
  input: App | VNode,
  context?: SSRContext,
): Promise<string>

Usage

1
2
3
4
5
6
7
8
9
10
11
12
const { createSSRApp } = require('vue')
const { renderToString } = require('@vue/server-renderer')

const app = createSSRApp({
  data: () => ({ msg: 'hello' }),
  template: `<div>{{ msg }}</div>`,
})

;(async () => {
  const html = await renderToString(app)
  console.log(html)
})()

Handling Teleports

If the rendered app contains teleports, the teleported content will not be part of the rendered string. Instead, they are exposed under the teleports property of the ssr context object:

1
2
3
4
const ctx = {}
const html = await renderToString(app, ctx)

console.log(ctx.teleports) // { '#teleported': 'teleported content' }

Streaming API

renderToNodeStream

Renders input as a Node.js Readable stream.

Signature

1
function renderToNodeStream(input: App | VNode, context?: SSRContext): Readable

Usage

1
2
// inside a Node.js http handler
renderToNodeStream(app).pipe(res)

Note: This method is not supported in the ESM build of @vue/server-renderer, which is decoupled from Node.js environments. Use pipeToNodeWritable instead.

pipeToNodeWritable

Render and pipe to an existing Node.js Writable stream instance.

Signature

1
2
3
4
5
function pipeToNodeWritable(
  input: App | VNode,
  context: SSRContext = {},
  writable: Writable,
): void

Usage

1
2
// inside a Node.js http handler
pipeToNodeWritable(app, {}, res)

renderToWebStream

Renders input as a Web ReadableStream.

Signature

1
2
3
4
function renderToWebStream(
  input: App | VNode,
  context?: SSRContext,
): ReadableStream

Usage

1
2
// inside an environment with ReadableStream support
return new Response(renderToWebStream(app))

Note: in environments that do not expose ReadableStream constructor in the global scope, pipeToWebWritable should be used instead.

pipeToWebWritable

Render and pipe to an existing Web WritableStream instance.

Signature

1
2
3
4
5
function pipeToWebWritable(
  input: App | VNode,
  context: SSRContext = {},
  writable: WritableStream,
): void

Usage

This is typically used in combination with TransformStream:

1
2
3
4
5
6
// TransformStream is available in environments such as CloudFlare workers.
// in Node.js, TransformStream needs to be explicitly imported from 'stream/web'
const { readable, writable } = new TransformStream()
pipeToWebWritable(app, {}, writable)

return new Response(readable)

renderToSimpleStream

Renders input in streaming mode using a simple readable interface.

Signature

1
2
3
4
5
6
7
8
9
10
function renderToSimpleStream(
  input: App | VNode,
  context: SSRContext,
  options: SimpleReadable,
): SimpleReadable

interface SimpleReadable {
  push(content: string | null): void
  destroy(err: any): void
}

Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
let res = ''

renderToSimpleStream(
  app,
  {},
  {
    push(chunk) {
      if (chunk === null) {
        // done
        console(`render complete: ${res}`)
      } else {
        res += chunk
      }
    },
    destroy(err) {
      // error encountered
    },
  },
)