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 (for building assets)

1. Install the package

Install LiVue via Composer:

composer require livue/livue

2. Publish the configuration

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 the assets

Publish the LiVue JavaScript bundle to your public directory:

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

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

Blade Setup

Add the LiVue directives to your main Blade layout to ensure styles, scripts and dynamic head elements are properly loaded.

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.

Tip — When inject_assets is enabled in the config (the default), LiVue automatically injects scripts and styles when it detects components on the page. In that case, you can skip the manual Blade directives.

Vite Integration

For development with HMR support, configure your app.js to import and start LiVue:

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

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

After publishing 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 component classes. By default, components are discovered in app/LiVue/ under the App\LiVue namespace.

layout

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