Installation

Requirements

Before installing LiVue, make sure your environment meets the following requirements:

PHP 8.2 or higher
Laravel 11 or higher
Vue.js 3.5 or higher
Node.js 18 or higher (optional, only for Vite/HMR workflows)

Required vs Optional — For a first component, you only need package install + component generation + rendering in Blade. Config publishing, static asset publishing, and Vite/HMR integration are optional.

1. Install the package (Required)

Install LiVue via Composer:

composer require livue/livue

2. Publish the configuration (Optional)

Publish the LiVue configuration file to customize settings:

php artisan vendor:publish --tag=livue-config

This creates config/livue.php where you can adjust component paths, middleware, layout defaults and more.

3. Publish static assets (Optional)

Only needed if you explicitly want the LiVue bundle in public/vendor/livue for custom deployment/performance strategies.

php artisan vendor:publish --tag=livue-assets

With default config (inject_assets = true), LiVue works without publishing this bundle.

Tip — You can also publish stubs with --tag=livue-stubs to customize the generated component templates.

Blade Setup (Optional)

Use manual Blade directives only if you disable automatic injection (inject_assets = false) or want strict manual control over asset placement.

resources/views/components/layouts/app.blade.php

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    @livueStyles
    @livueHead
</head>
<body>
    {{ $slot }}

    @livueScripts
</body>
</html>

@livueStyles — Injects the LiVue CSS into the <head>.
@livueHead — Renders dynamic head elements managed by your components (meta tags, title, etc.).
@livueScripts — Loads the LiVue JavaScript runtime. Place it before the closing </body> tag.

Default behavior — With inject_assets enabled (default), LiVue auto-injects scripts/styles when it detects components, so this entire section can be skipped for first setup.

Vite Integration (Optional)

Needed only if you want to run LiVue through your app's Vite pipeline (for HMR/custom frontend setup). Not required for a basic first component.

resources/js/app.js

import LiVue from 'livue';

LiVue.start();

Then make sure your Vite configuration uses the Vue full build (runtime + compiler), which is required for LiVue to compile templates in the browser:

vite.config.js

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
    resolve: {
        alias: {
            'vue': 'vue/dist/vue.esm-bundler.js',
        },
    },
    plugins: [
        laravel({
            input: ['resources/js/app.js'],
            refresh: true,
        }),
        tailwindcss(),
    ],
});

Important — The vue alias to vue/dist/vue.esm-bundler.js is critical. Without it, Vue's template compiler is not included and components will render as empty HTML comments.

Your First Component

Minimal path — In most apps, this section plus composer require livue/livue is enough to get started.

Generate a new LiVue component using the Artisan command:

php artisan make:livue Counter

This creates two files:

- app/LiVue/Counter.php — The PHP component class
- resources/views/livue/counter.blade.php — The Blade template

The generated PHP class defines your component's state and actions:

app/LiVue/Counter.php

<?php

namespace App\LiVue;

use LiVue\Component;

class Counter extends Component
{
    public int $count = 0;

    public function increment()
    {
        $this->count++;
    }
}

And the Blade template uses Vue directives for reactivity:

resources/views/livue/counter.blade.php

<div>
    <p>Count: {{ count }}</p>
    <button v-click="increment">
        Add
    </button>
</div>

Render the component in any Blade view using the @livue directive:

@livue('counter')

Tip — You can also use php artisan livue:component Counter as an alias. Add --single for a Single File Component or --multi for a Multi File Component.

Configuration

If you publish the config file, you will find it at config/livue.php. Here are the main options:

config/livue.php

return [
    // Auto-inject CSS and JS when components are detected
    'inject_assets' => true,

    // URL prefix for AJAX endpoints
    'route_prefix' => 'livue',

    // Middleware applied to AJAX endpoints
    'middleware' => ['web'],

    // Namespace for auto-discovery of components
    'component_namespace' => 'App\\LiVue',

    // Filesystem path where components live
    'component_path' => app_path('LiVue'),

    // Default layout for page components
    'layout' => 'components.layouts.app',
];

inject_assets

When true (the default), LiVue automatically detects components on the page and injects the required JavaScript and CSS. Set to false if you prefer to include assets manually via Blade directives or Vite.

route_prefix

The URL prefix used for LiVue's internal AJAX endpoints. Change this if it conflicts with your application routes.

component_namespace & component_path

Define where LiVue looks for your primary component classes. By default, components are discovered in app/LiVue/ under the App\LiVue namespace.

If you need extra component namespaces (for modules/packages), keep your main namespace in config and register additional ones at boot time:

use LiVue\Facades\LiVue;

public function boot(): void
{
    LiVue::registerNamespace([
        'App\\Admin\\LiVue',
        'App\\Billing\\LiVue',
    ]);
}

layout

The default Blade layout used by page components. You can generate a layout with php artisan livue:layout or override it per-component.