Laravel Splade Laravel Package

Getting Started

Splade gives you an Inertia-style SPA without leaving Blade. The mental model: your controllers are untouched (they still return view() and redirect()), Blade renders the page server-side as usual, and a bundled Vue 3 runtime hydrates it and intercepts navigation/forms. There is no npm build step for the base feature set — that is the package's entire pitch.

Minimal install:

composer require protonemedia/laravel-splade
php artisan splade:install

Laravel 12 requires 1.4.21 or later — that's the release where Laravel Shift contributed 12.x compatibility. On Laravel 11 or below any recent 1.4.x is fine, but there's no reason to pin below 1.4.21 since the only changes since 1.4.20 are dependency bumps and that compatibility patch.

If the installer isn't available on your version, the equivalent is: publish the config (php artisan vendor:publish --tag=splade-config), create the root Blade template, and register ProtoneMedia\Splade\Http\SpladeMiddleware on the web group (in Laravel 11+: $middleware->web(append: [\ProtoneMedia\Splade\Http\SpladeMiddleware::class]);).

The root template is the only mandatory view:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @spladeHead
</head>
<body>
    @splade
</body>
</html>

@splade mounts the app; without it nothing hydrates and you'll get silent full-page reloads.

First use case: pick one existing CRUD screen. Wrap the form in <x-splade-form>, replace <input> with <x-splade-input>, and swap internal <a> tags for <x-splade-link>. You now have client-side navigation with automatic CSRF handling and 422 validation errors bound to fields — with zero controller changes.

Implementation Patterns

Forms are the core loop. Keep the controller exactly as Laravel intends:

<x-splade-form :default="$user" :action="route('users.update', $user)" method="put">
    <x-splade-input name="name" label="Name" />
    <x-splade-input name="email" type="email" label="Email" />
    <x-splade-select name="role" :options="$roles" />
    <x-splade-checkbox name="active" label="Active" />
    <x-splade-submit label="Save" />
</x-splade-form>

public function update(Request $request, User $user)
{
    $user->update($request->validate([
        'name' => ['required', 'string'],
        'email' => ['required', 'email'],
    ]));

    return redirect()->route('users.index')->with('success', 'Saved.');
}

The name attributes are the contract — validation errors, :default, and v-model all key off them. :default accepts an Eloquent model, array, or closure.

Tables replace hand-rolled index pages. Build the dataset in the controller, render in Blade:

return view('users.index', [
    'users' => SpladeTable::for(User::class)
        ->column('name', searchable: true, sortable: true)
        ->column('email', searchable: true)
        ->column('actions'),
]);

<x-splade-table :for="$users">
    <x-splade-cell actions as $user">
        <x-splade-link :href="route('users.edit', $user)" modal>Edit</x-splade-link>
    </x-splade-cell>
</x-splade-table>

Search, sort, and pagination round-trip through the query string automatically — which means index state is bookmarkable and back-button-safe.

Modals come in two flavours: <x-splade-modal> as a wrapper in a page, or a normal route page opened via <x-splade-link modal>. The route still returns a full Blade view; Splade extracts it into the modal.

Client-side state without writing a Vue component:

<x-splade-data :default="{ count: 0 }">
    <button @click="data.count++">@{{ data.count }}</button>
</x-splade-data>

Partial reloads for slow widgets: <x-splade-defer> with a request prop lets a section load after the shell, which keeps Time-to-First-Byte honest when a dashboard aggregates expensive queries.

Flash and toasts stay server-driven — session()->flash() plus Splade::flash() / Splade::toast() in the controller. Because redirects are intercepted, the flash arrives without a page reload.

Testing stays boring, which is the point: Pest/PHPUnit feature tests hit the same controllers and assert the same redirects and validation errors. Only add browser tests for hydration-sensitive behaviour.

Gotchas and Tips

• Maintenance mode, not active development. 1.4.21 shipped Laravel 12 compatibility courtesy of @laravel-shift, and the rest of the release is Dependabot noise — that is the shape of everything you should expect from here on. Treat it as a stable-but-frozen package: compatibility patches may land, features and Vue upgrades will not. Assume no Laravel 13 support until a similar patch appears, and don't count on security fixes arriving quickly. For existing apps it's fine; for new projects in 2025+, Inertia + Vue or Livewire 3 is the safer bet. Plan an exit before you deepen the dependency.
• Upgrading to Laravel 12 without bumping Splade will bite you. Bump the package first (composer require protonemedia/laravel-splade:^1.4.21), and run your feature test suite before touching the framework — the middleware and view-component surface is what breaks, and it breaks loudly in the network tab rather than at boot.
• Plain <a> and <form> silently break the SPA. Everything looks fine in dev until you notice full reloads. Audit with a grep for <a href and <form in any view you Splade-ify.
• Missing @splade is the number-one "nothing works" bug. Symptom: page renders but has no reactivity, forms POST normally. Check the root template first.
• Debug with the network tab, not dd(). Splade distinguishes navigations by request/response headers; the server returns JSON instead of HTML when the SPA is driving. If you see HTML where you expect JSON, the middleware isn't running or the link wasn't a Splade link. dd() inside a controller will corrupt the SPA response — use Log::info().
• Blade and Vue share {{ }}. In x-splade-data scopes, escape with @{{ }} or you'll get "undefined variable" errors. This is the most common friction for developers new to the package.
• name attribute mismatches fail quietly. x-splade-form binds errors by field name; a typo means the 422 arrives but nothing highlights. Compare the input name against the validation rules array.
• SSR is optional but expensive. It requires a long-running Node process alongside PHP and is the biggest deployment headache. Most teams ship without it; if SEO matters, confirm rendering with curl (no JS) before assuming it works.
• Tables scale poorly by default. SpladeTable::for(User::class) on a large table without explicit column selection and a sane ->paginate() will select * and sort unindexed columns. Treat it like a query builder, not magic.
• Extension points: custom Vue components go through Vite and are registered with the Splade app instance; server-side you can share data globally. Check config/splade.php before overriding templates — the head/meta and toast configuration live there.
• Escape hatch: because routes, controllers, and Blade views are conventional Laravel, migrating away is mostly a view-layer rewrite plus swapping x-splade-* components for Inertia links/forms or Livewire components. Keep controllers free of Splade-specific calls where you can, and the exit stays cheap. A 1.4.21-style compatibility patch is a reprieve, not a revival — don't read it as a signal to invest further.