Skip to main content
LiveVue provides server-side rendering (SSR) capabilities through the LiveVue.SSR behaviour and two built-in implementations: LiveVue.SSR.NodeJS and LiveVue.SSR.ViteJS.

​
LiveVue.SSR

A behaviour for rendering Vue components server-side. This module defines the interface that SSR implementations must follow and provides the main render/3 function.

​
Configuration

To define a custom renderer, change the application config in config.exs: 
config :live_vue, ssr_module: MyCustomSSRModule

​
render/3

Renders a Vue component server-side. 
render(name, props, slots)
​
name
String.t()
required
The name of the Vue component to render.
​
props
map
required
A map of props to pass to the component. Keys can be strings or atoms.
​
slots
map
required
A map of slots to pass to the component. Keys can be strings or atoms.
​
return
map
A render response with the following shape:
%{
  html: "<div>...</div>",
  preloadLinks: "<link rel='modulepreload' ...>"
}

​
Telemetry

The module exposes a telemetry span for each render under the key [:live_vue, :ssr]. The metadata includes:
  • component - Component name
  • props - Props passed to the component
  • slots - Slots passed to the component

​
LiveVue.SSR.NodeJS

Implements SSR by using a Node.js subprocess. This is the recommended approach for production deployments.

​
How it works

Under the hood, it invokes the render function exposed by the server.js file. You can see how server.js is created by looking at the assets.deploy command and package.json build-server script.

​
Configuration

Add the NodeJS supervisor to your application.ex: 
children = [
  # ...
  {NodeJS.Supervisor, [path: LiveVue.SSR.NodeJS.server_path(), pool_size: 4]}
]
Optionally configure the SSR file path in config.exs: 
config :live_vue, ssr_filepath: "./static/server.mjs"

​
render/3

Renders a Vue component using Node.js. 
render(name, props, slots)
​
name
String.t()
required
The name of the Vue component to render.
​
props
map
required
Props to pass to the component.
​
slots
map
required
Slots to pass to the component.
​
return
String.t()
Returns the rendered HTML as a binary string.
If NodeJS is not configured, this function raises LiveVue.SSR.NotConfigured.

​
server_path/0

Returns the path to the Node.js server directory. 
server_path()
​
return
String.t()
Returns the application’s priv directory path.

​
LiveVue.SSR.ViteJS

Implements SSR by making HTTP requests to a Vite development server. This is the recommended approach for development.

​
How it works

Makes a POST request to http://{:vite_host}/ssr_render. The ssr_render endpoint is implemented as a Vite plugin.

​
Configuration

Add the LiveVue plugin to your vite.config.js: 
import liveVuePlugin from "live_vue/vitePlugin"
import vue from "@vitejs/plugin-vue"

export default {
  publicDir: "static",
  plugins: [vue(), liveVuePlugin()],
  // ...
}
Configure the Vite host in config/dev.exs: 
config :live_vue, vite_host: "http://localhost:5173"

​
render/3

Renders a Vue component using Vite’s dev server. 
render(name, props, slots)
​
name
String.t()
required
The name of the Vue component to render.
​
props
map
required
Props to pass to the component.
​
slots
map
required
Slots to pass to the component.
​
return
String.t() | {:error, String.t()}
Returns the rendered HTML as a binary string, or an error tuple with a descriptive message.
Error responses include:
  • Connection failures (Vite not running)
  • 500 errors with stack traces from Vite
  • Unexpected HTTP status codes
If Vite host is not configured, this function raises LiveVue.SSR.NotConfigured.

​
vite_path/1

A handy utility for constructing paths relative to the Vite host. 
vite_path(path)
​
path
String.t()
required
The path to append to the Vite host URL.
​
return
String.t()
Returns the full URL by joining the configured Vite host with the provided path.

​
Exception: LiveVue.SSR.NotConfigured

Raised when SSR is attempted but the required configuration is missing. The exception message contains specific instructions for fixing the configuration issue.

Build docs developers (and LLMs) love

Get started for freeTalk to us