Installation

Requirements

Before installing Gale, ensure your environment meets these requirements:

PHP 8.2 or higher
Laravel 11 or higher
Alpine.js 3.x (included with Gale)

Note

Gale bundles Alpine.js (v3) with the Morph plugin. You don't need to install Alpine separately—Gale handles it for you.

Install via Composer

Install Gale using Composer:

1composer require dancycodes/gale

composer require dancycodes/gale

Then run the install command to publish the JavaScript assets:

1php artisan gale:install

php artisan gale:install

That's it! The install command publishes the JavaScript assets and registers the service provider automatically.

Add the @gale Directive

Add the @gale directive to your layout file's <head> section. This single directive loads everything Gale needs:

1<!-- resources/views/layouts/app.blade.php -->
2<head>
3    @gale
4</head>

<!-- resources/views/layouts/app.blade.php -->
<head>
    @gale
</head>

What @gale Outputs

The directive outputs two things:

A CSRF meta tag for protected requests
The Gale JavaScript bundle containing Alpine.js, Morph plugin, and Gale's HTTP magics

Tip

The bundled gale.js includes Alpine.js (v3), Alpine Morph for intelligent DOM diffing, and all Gale magics like $get, $post, and SSE handling.

Existing Alpine.js Projects

Since Gale bundles Alpine.js, you must remove any existing Alpine installation to prevent conflicts. Running two instances of Alpine causes unpredictable behavior.

Remove Existing Alpine

Having duplicate Alpine instances will break your application. Gale provides Alpine, so remove your existing installation.

If Using CDN

Remove the Alpine.js script tag from your layout:

1<!-- Remove this line -->
2<script defer src="https://cdn.jsdelivr.net/npm/alpinejs"></script>

<!-- Remove this line -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs"></script>

If Using npm/Vite

Remove Alpine imports from your JavaScript entry file:

1// resources/js/app.js - Remove these lines:
2import Alpine from 'alpinejs';
3window.Alpine = Alpine;
4Alpine.start();

// resources/js/app.js - Remove these lines:
import Alpine from 'alpinejs';
window.Alpine = Alpine;
Alpine.start();

Using Additional Alpine Plugins

Gale exposes window.Alpine globally, so you can still register additional Alpine plugins like Persist, Mask, or Focus.

Inline Script

Use the alpine:init event to register plugins before Alpine starts:

1<head>
2    @gale
3    <script>
4        document.addEventListener('alpine:init', () => {
5            Alpine.plugin(yourPlugin);
6        });
7    </script>
8</head>

<head>
    @gale
    <script>
        document.addEventListener('alpine:init', () => {
            Alpine.plugin(yourPlugin);
        });
    </script>
</head>

Bundled JavaScript

Or in your bundled JavaScript file:

1// resources/js/app.js
2import persist from '@alpinejs/persist';
3
4// Alpine is available globally via @gale
5window.Alpine.plugin(persist);

// resources/js/app.js
import persist from '@alpinejs/persist';

// Alpine is available globally via @gale
window.Alpine.plugin(persist);

Configuration (Optional)

Gale works out of the box without configuration. However, you can publish the config file to customize route discovery and other options:

1php artisan vendor:publish --tag=gale-config

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

This creates config/gale.php where you can enable route discovery and configure controller/view directories.

Verify Installation

Let's verify Gale works by building a simple counter. This demonstrates the core concept: your Laravel controller drives the UI reactivity.

1. Add the Routes

1// routes/web.php
2Route::get('/gale-test', fn() => view('gale-test'));
3
4Route::post('/gale-test/increment', function () {
5    $count = request()->state('count', 0);
6
7    return gale()->state('count', $count + 1);
8});

// routes/web.php
Route::get('/gale-test', fn() => view('gale-test'));

Route::post('/gale-test/increment', function () {
    $count = request()->state('count', 0);

    return gale()->state('count', $count + 1);
});

2. Create the View

 1<!-- resources/views/gale-test.blade.php -->
 2<!DOCTYPE html>
 3<html>
 4<head>
 5    @gale
 6</head>
 7<body>
 8    <div x-data="{ count: 0 }">
 9        <h1>Count: <span x-text="count"></span></h1>
10        <button @click="$postx('/gale-test/increment')">+1</button>
11    </div>
12</body>
13</html>

<!-- resources/views/gale-test.blade.php -->
<!DOCTYPE html>
<html>
<head>
    @gale
</head>
<body>
    <div x-data="{ count: 0 }">
        <h1>Count: <span x-text="count"></span></h1>
        <button @click="$postx('/gale-test/increment')">+1</button>
    </div>
</body>
</html>

3. Test It

Visit /gale-test and click the button. Each click sends the current count to your server, which increments it and pushes the new value back—the UI updates instantly without a page reload.

Gale is Working!

No JavaScript written. No API endpoints designed. Your Laravel controller drives the UI reactivity. This same pattern scales to forms, wizards, real-time dashboards, and more.

Updating Gale

When updating Gale, run the install command again to update the JavaScript assets:

1composer update dancycodes/gale
2php artisan gale:install

composer update dancycodes/gale
php artisan gale:install