@vue/server-renderer

What is @vue/server-renderer?

The @vue/server-renderer package is designed for server-side rendering (SSR) of Vue.js applications. It allows developers to render Vue components on the server and send the rendered HTML to the client, improving the initial load time and SEO for Vue.js applications. This package is part of the Vue.js ecosystem and is specifically tailored for Vue 3.x applications.

What are @vue/server-renderer's main functionalities?

Rendering a Vue Component to a String

This feature allows you to render a Vue component to an HTML string on the server. This is useful for generating the initial HTML for a page on the server, which can then be sent to the client for faster initial load times and better SEO.

const { createSSRApp } = require('vue');
const { renderToString } = require('@vue/server-renderer');

const app = createSSRApp({
  data: () => ({ msg: 'Hello, server-side rendering!' }),
  template: '<div>{{ msg }}</div>'
});

renderToString(app).then(html => {
  console.log(html);
});

Streaming a Vue Component

This feature enables streaming rendering of a Vue component. Instead of waiting for the entire component to be rendered before sending it to the client, the rendered output is streamed to the client as it's generated. This can improve the perceived performance of the application.

const { createSSRApp } = require('vue');
const { renderToNodeStream } = require('@vue/server-renderer');
const express = require('express');
const app = express();

const vueApp = createSSRApp({
  data: () => ({ msg: 'Hello, streaming SSR!' }),
  template: '<div>{{ msg }}</div>'
});

app.get('/', (req, res) => {
  res.setHeader('Content-Type', 'text/html');
  const stream = renderToNodeStream(vueApp);
  stream.pipe(res);
});

app.listen(3000);

0

README

@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

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

Usage

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:

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

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

Usage

// 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

function pipeToNodeWritable(
  input: App | VNode,
  context: SSRContext = {},
  writable: Writable,
): void

Usage

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

renderToWebStream

Renders input as a Web ReadableStream.

Signature

function renderToWebStream(
  input: App | VNode,
  context?: SSRContext,
): ReadableStream

Usage

// 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

function pipeToWebWritable(
  input: App | VNode,
  context: SSRContext = {},
  writable: WritableStream,
): void

Usage

This is typically used in combination with TransformStream:

// 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

function renderToSimpleStream(
  input: App | VNode,
  context: SSRContext,
  options: SimpleReadable,
): SimpleReadable

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

Usage

let res = ''

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

Changelog

3.5.14 (2025-05-15)

Bug Fixes

• compat: correct deprecation message for v-bind.sync usage (#13137) (466b30f), closes #13133
• compiler-core: remove slot cache from parent renderCache during unmounting (#13215) (5d166f3)
• compiler-sfc: fix scope handling for props destructure in function parameters and catch clauses (8e34357), closes #12790
• compiler-sfc: treat the return value of useTemplateRef as a definite ref (#13197) (8ae1122)
• compiler: fix spelling error in domTagConfig (#13043) (388295b)
• customFormatter: properly accessing ref value during debugger (#12948) (fdbd026)
• hmr/teleport: adjust static children traversal for HMR in dev mode (#12819) (5e37dd0), closes #12816
• hmr: avoid hydration for hmr root reload (#12450) (1f98a9c), closes vitejs/vite-plugin-vue#146 vitejs/vite-plugin-vue#477
• hmr: avoid hydration for hmr updating (#12262) (9c4dbbc), closes #7706 #8170
• reactivity: ensure markRaw objects are not reactive (#12824) (295b5ec), closes #12807
• reactivity: ensure multiple effectScope on() and off() calls maintains correct active scope (22dcbf3), closes #12631 #12632 #12641
• reactivity: should not recompute if computed does not track reactive data (#12341) (0b23fd2), closes #12337
• runtime-core: stop tracking deps in setRef during unmount (#13210) (016c472)
• runtime-core: update __vnode of static nodes when patching along the optimized path (#13223) (b3ecee3)
• runtime-core: inherit comment nodes during block patch in production build (#10748) (6264505), closes #10747 #12650
• runtime-core: prevent unmounted vnode from being inserted during transition leave (#12862) (d6a6ec1), closes #12860
• runtime-core: respect immutability for readonly reactive arrays in v-for (#13091) (3f27c58), closes #13087
• runtime-dom: always treat autocorrect as attribute (#13001) (1499135), closes #5705
• slots: properly warn if slot invoked in setup (#12195) (9196222), closes #12194
• ssr: properly init slots during ssr rendering (#12441) (2206cd2), closes #12438
• transition: fix KeepAlive with transition out-in mode behavior in production (#12468) (343c891), closes #12465
• TransitionGroup: reset prevChildren to prevent memory leak (#13183) (8b848cb), closes #13181
• types: allow return any for Options API lifecycle hooks (#5914) (06310e8)
• types: the directive's modifiers should be optional (#12605) (10e54dc)
• typos: fix comments referencing transformElement.ts (#12551)[ci-skip] (11c053a)

Features

• types: add type TemplateRef (#12645) (636a861)