Configuration

This guide covers all configuration options available in LiveVue, from basic setup to advanced customization.

Application Configuration

LiveVue configuration is managed in your config/config.exs file:

import Config

config :live_vue,
  # SSR module selection
  # For development: LiveVue.SSR.ViteJS
  # For production: LiveVue.SSR.QuickBEAM (default) or LiveVue.SSR.NodeJS
  ssr_module: nil,

  # Default SSR behavior
  # Can be overridden per-component with v-ssr={true|false}
  ssr: true,

  # Vite development server URL
  # Typically http://localhost:5173 in development
  vite_host: nil,

  # SSR server bundle path (relative to priv directory)
  # Created by the Mix assets build/deploy alias
  ssr_filepath: "./static/server.mjs",

  # Testing configuration
  # When false, we will always update full props and not send diffs
  # Useful for testing scenarios where you need complete props state
  enable_props_diff: true,

  # Raise when duplicate LiveVue component ids are registered during SSR
  # Defaults to true in dev and false elsewhere
  validate_unique_component_ids: Mix.env() == :dev,

  # Gettext backend for translating form validation errors
  # When set, Phoenix.HTML.Form errors are translated using this backend
  # Example: MyApp.Gettext
  gettext_backend: nil

Environment-Specific Configuration

Recommended development Configuration

# config/dev.exs
config :live_vue,
  ssr_module: LiveVue.SSR.ViteJS,
  vite_host: "http://localhost:5173",
  ssr: true

Recommended Production Configuration

# config/prod.exs
config :live_vue,
  ssr_module: LiveVue.SSR.QuickBEAM,
  ssr: true

# or use Node.js-based SSR (requires Node.js 24+ in production):
# ssr_module: LiveVue.SSR.NodeJS

# or disable SSR entirely:
# ssr_module: nil, ssr: false

Vue Application Setup

Configure your Vue application in assets/vue/index.js. You should use createLiveVue to provide two required functions:

Installation step provides a reasonable implementation of createLiveVue that you can use as a starting point.

Basic Configuration

import "vite/modulepreload-polyfill"
import { h } from "vue"
import { createLiveVue, findComponent } from "live_vue"

export default createLiveVue({
  // Component resolution - adjust this to your needs
  // Eg. You might want to import some components directly from node_modules
  // or lazy load components
  resolve: name => {
    const components = {
      ...import.meta.glob("./**/*.vue", { eager: true }),
      ...import.meta.glob("../../lib/**/*.vue", { eager: true }),
    }

    // findComponent resolves by matching path segments from the end.
    // It handles both Component.vue and Component/index.vue patterns,
    // and throws helpful errors for not-found or ambiguous matches.
    return findComponent(components, name)
  },

  // Vue app setup
  setup: ({ createApp, component, props, slots, plugin, el }) => {
    const app = createApp({ render: () => h(component, props, slots) })
    app.use(plugin)
    app.mount(el)
    return app
  },
})

SetupContext

SetupContext is an object that is passed to the setup function.

Component Resolution Options

Eager Loading (Default)

All components are bundled with the main application:

const components = {
  ...import.meta.glob("./**/*.vue", { eager: true }),
}

Lazy Loading

If you want to lazy load components, you can use the import function:

const components = {
  Counter: () => import("./Counter.vue"),
  Modal: () => import("./Modal.vue")
}

// Or using Vite's glob import
// useful if we colocate Vue components with LiveView components and want to put each of them into a separate chunk
// all shared components imported by top-level components will be included as well.
const components = import.meta.glob(
  "../../lib/**/*.vue",
  { eager: false, import: 'default' }
)

Custom Resolution Logic

resolve: name => {
  // Custom component mapping and lazy loading
  const componentMap = {
    'MyCounter': () => import('./components/Counter.vue'),
    'admin/Dashboard': () => import('./admin/Dashboard.vue')
  }

  return componentMap[name]
}

Vue App Customization

Add plugins, stores, and other Vue features:

import { createPinia } from "pinia"
import { createI18n } from "vue-i18n"

export default createLiveVue({
  setup: ({ createApp, component, props, slots, plugin, el, ssr }) => {
    const app = createApp({ render: () => h(component, props, slots) })

    // LiveVue plugin (required)
    app.use(plugin)

    // Add your plugins
    const pinia = createPinia()
    app.use(pinia)

    const i18n = createI18n({
      locale: 'en',
      messages: { /* your translations */ }
    })
    app.use(i18n)

    // SSR-specific setup
    if (ssr) {
      // Server-side specific initialization
    }

    app.mount(el)
    return app
  }
})

Component Organization

Directory Structure

By default, Vue components are resolved from:

• assets/vue/ - Main Vue components directory
• lib/my_app_web/ - Colocated with LiveView files

Custom Vue Root Directories

Configure component discovery paths in your LiveView module:

# lib/my_app_web.ex
defmodule MyAppWeb do
  def html_helpers do
    quote do
      use LiveVue.Components, vue_root: [
        "./assets/vue",
        "./lib/my_app_web",
        "./lib/my_app_web/components"
      ]
    end
  end
end

This generates shortcut functions for your components:

# Instead of
<.vue v-component="Counter" />

# You can use
<.Counter />

Component Naming Conventions

Components are resolved by name or path suffix:

• Counter.vue → accessible as "Counter"
• path/to/Component.vue → accessible as "path/to/Component" or "Component"
• path/to/component/index.vue → accessible as "path/to/component" or "component"

Server-Side Rendering (SSR)

LiveVue provides flexible SSR options that work great in both development and production environments.

SSR Modules

LiveVue offers two SSR strategies depending on your environment:

ViteJS (Development)

Perfect for development with hot module replacement:

# config/dev.exs
config :live_vue,
  ssr_module: LiveVue.SSR.ViteJS,
  vite_host: "http://localhost:5173"

Uses Vite's ssrLoadModule for efficient development compilation with instant updates.

NodeJS (Production)

Uses elixir-nodejs with a pre-built server bundle. Requires Node.js 24+ in production:

# config/prod.exs
config :live_vue,
  ssr_module: LiveVue.SSR.NodeJS,
  ssr: true

QuickBEAM (Production)

Runs JavaScript inside the BEAM via an embedded QuickBEAM runtime. No external Node.js installation required. Requires quickbeam:

# config/prod.exs
config :live_vue,
  ssr_module: LiveVue.SSR.QuickBEAM,
  ssr: true

See LiveVue.SSR.QuickBEAM module docs for setup instructions.

SSR Configuration

Control SSR behavior globally or per-component:

# Global SSR settings
config :live_vue,
  ssr: true,  # Enable SSR by default
  ssr_filepath: "./static/server.mjs"  # Server bundle path

SSR Behavior

SSR is intelligently applied:

• Runs during: Initial page loads (dead renders)
• Skips during: Live navigation and WebSocket updates
• Can be disabled: Per-component with v-ssr={false}

This gives you the SEO and performance benefits of SSR without the overhead during live updates.

Per-Component SSR Control

Override global settings for specific components:

<!-- Force SSR for this component -->
<.vue v-component="CriticalContent" v-ssr={true} />

<!-- Disable SSR for client-only widgets -->
<.vue v-component="InteractiveChart" v-ssr={false} />

<!-- Use global default -->
<.vue v-component="RegularComponent" />

Testing Configuration

LiveVue provides testing-specific configuration options to help with component testing and debugging.

enable_props_diff

By default, LiveVue optimizes performance by only sending prop changes (diffs) to the client. However, during testing, you may need access to the complete props state rather than just the incremental changes.

# config/test.exs
config :live_vue,
  enable_props_diff: false

When disabled:

• LiveVue will always send full props and not send diffs
• The props field returned by LiveVue.Test.get_vue/2 will contain the complete props state
• This makes it easier to write comprehensive tests that verify the full component state
• Useful for debugging component behavior and ensuring all props are correctly passed

Note: This option is primarily intended for testing scenarios. In production, the default behavior (sending only diffs) provides better performance.

validate_unique_component_ids

LiveVue can raise when the same component id is registered more than once during SSR. This catches duplicate DOM ids early and prevents SSR injection cache collisions.

config :live_vue,
  validate_unique_component_ids: true

By default this check is enabled in development and disabled elsewhere. Set it to false to allow duplicate ids, although duplicate DOM ids can still cause browser and hydration issues.

SSR Performance

Vue SSR is compiled into optimized string concatenation for maximum performance. The SSR process:

• Only runs during "dead" renders (no WebSocket connection)
• Skips during live navigation for better UX
• Can be disabled per-component when not needed

Production SSR Setup

The default production setup uses QuickBEAM, which runs JavaScript inside the BEAM — no Node.js needed at runtime.

1. Add QuickBEAM to your supervision tree in application.ex:

children = [
  LiveVue.SSR.QuickBEAM,
  # ... other children
]

2. Build server bundle as part of your deployment:

# In your deployment script
mix assets.deploy

The installer configures the Mix asset alias to run both the client Vite build and the SSR build:

"assets.deploy": [
  "phoenix_vite.npm vite build --manifest --ssrManifest --emptyOutDir true",
  "phoenix_vite.npm vite build --emptyOutDir false --ssr js/server.js --outDir ../priv/static"
]

The SSR bundle will be created at priv/static/server.mjs and loaded by QuickBEAM at startup.

SSR Troubleshooting

SSR not working in development?

• Check that Vite dev server is running on the configured port
• Verify vite_host matches your Vite server URL

SSR failing in production?

• Check that priv/static/server.mjs exists after build
• Verify LiveVue.SSR.QuickBEAM is in your supervision tree
• Ensure {:quickbeam, "~> 0.8"} is in your dependencies

Performance issues?

• Disable SSR for components that don't benefit from it

Shared Props

Shared props let you automatically inject common assigns (flash, current user, etc.) into LiveVue component tags without repeating them in every template. The same ~H override also injects v-socket automatically.

This works by overriding the ~H sigil to rewrite HEEX templates at compile time, injecting the configured props as explicit attributes. Because the props appear as regular template expressions, LiveView's change tracking works correctly.

History: The runtime-based shared_props option was removed in v1.0.0 because it bypassed LiveView's change tracking. This compile-time approach replaces it.

Configuration

Define shared props in config/config.exs:

config :live_vue,
  shared_props: [
    :flash,
    {:current_user, :user},
    {[:current_scope, :workspace], :workspace}
  ]

Three formats are supported:

Setup

In your lib/my_app_web.ex, override the ~H sigil in html_helpers:

defp html_helpers do
  quote do
    # ... existing imports ...
    use LiveVue

    use LiveVue.Components, vue_root: ["./assets/vue", "./lib/my_app_web"]

    # Override ~H to inject shared props and v-socket into LiveVue tags
    import Phoenix.Component, except: [sigil_H: 2]
    import LiveVue.SharedPropsView, only: [sigil_H: 2]
  end
end

New projects get this automatically via mix live_vue.install.

How It Works

When you write:

~H"""
<.vue v-component="MyComponent" posts={@posts} />
"""

With shared_props: [:flash, {:current_user, :user}], the sigil rewrites the template to:

~H"""
<.vue v-component="MyComponent" posts={@posts}
      v-socket={get_in(assigns, [:socket])}
      flash={get_in(assigns, [:flash])}
      user={get_in(assigns, [:current_user])} />
"""

Props explicitly passed on a tag are never duplicated. That applies both to user-configured shared props and to the builtin v-socket injection.

LiveVue tags are rewritten, including shortcut helpers generated by LiveVue.Components. If you call LiveVue.vue/1 directly, pass v-socket explicitly there.

Troubleshooting Configuration

Common Issues

1. Components not found: Check vue_root paths in LiveVue.Components
2. SSR errors: Verify ssr_module and vite_host configuration
3. TypeScript errors: Ensure proper tsconfig.json setup
4. Build failures: Check Vite configuration and entry points

Debug Configuration

Enable debug logging:

config :logger, level: :debug

# In your component
require Logger
Logger.debug("Vue component props: #{inspect(props)}")

# on the frontend, use VueDevTools to debug

Next Steps

With your configuration complete, explore:

• Getting Started for your first component
• Basic Usage for common patterns