README

By default, every link click in Laravel loads a full new page — HTML, CSS, JS, fonts, everything re-downloads. BladeFlow skips that. Only the content changes, the rest stays. Faster, smoother, no white flash between pages.

Most Laravel SPA solutions force you to either abandon Blade entirely (Inertia) or add jQuery (pjax). This package adds that same speed on top of your existing Blade views — no rewrite, nothing changes except how fast it feels.

Quick Start

composer require thbappy7706/bladeflow
php artisan vendor:publish --tag=bladeflow-assets

Add /public/vendor to your .gitignore to avoid committing published assets.

Setup — `@extends` / `@section`

1. Layout file

Add @bladeflowContent to your content wrapper and @bladeflowEngine before </body>. Make sure @yield('script') comes after @bladeflowEngine.

<main @bladeflowContent>
    @yield('content')
</main>

@bladeflowEngine
@yield('script')

2. Navigation links

Add @bladeflow to links you want SPA navigation on. Links without @bladeflow do a normal full reload.

<a href="{{ route('home') }}" @bladeflow>Home</a>
<a href="{{ route('about') }}" @bladeflow>About</a>
<a href="{{ route('logout') }}">Logout</a>

3. Controller

public function home()
{
    return bladeflow('pages.home');
}

public function about()
{
    return bladeflow('pages.about', compact('data'));
}

4. Page views — no changes needed

@extends('layouts.app')

@section('title', 'Home')

@section('style')
    <style>
        .hero { background: #1a3c6e; color: #fff; padding: 60px; }
    </style>
@endsection

@section('content')
    <div class="hero">
        <h1>Welcome</h1>
    </div>
@endsection

@section('script')
    <script>
        console.log('page loaded');
    </script>
@endsection

Setup — `x-layout` components

1. Layout component

Add @bladeflowContent to your content wrapper and @bladeflowEngine before </body>.

<head>
    <style data-bladeflow-layout-style>
        /* global styles — marked so they aren't re-injected on navigation */
    </style>

    {{ $style ?? '' }}
</head>
<body>
    <main @bladeflowContent>
        {{ $slot }}
    </main>

    <script data-bladeflow-layout-script>
        /* global scripts — marked so they don't re-run on navigation */
    </script>

    @bladeflowEngine
    {{ $script ?? '' }}
</body>

2. Navigation links — same as above, add @bladeflow:

<a href="{{ route('home') }}" @bladeflow>Home</a>
<a href="{{ route('logout') }}">Logout</a>

3. Controller — same as above:

public function home()
{
    return bladeflow('pages.home');
}

4. Page views

<x-app-layout title="Home">

    <x-slot:style>
        <style>
            .hero { background: #1a3c6e; color: #fff; padding: 60px; }
        </style>
    </x-slot:style>

    <div class="hero">
        <h1>Welcome</h1>
    </div>

    <x-slot:script>
        <script>
            console.log('page loaded');
        </script>
    </x-slot:script>

</x-app-layout>

What works out of the box

URL updates, back/forward button, refresh, direct links — all work
Per-page styles and scripts load and unload on every navigation
Session expiry redirects cleanly instead of breaking
Hover prefetch — pages start loading before you even click
Works with both @extends and x-layout

Progress Indicator & Lifecycle Events

BladeFlow includes a built-in, zero-dependency top progress bar loader with a modern Indigo-to-Cyan gradient and glow effect that runs automatically during SPA transitions.

Disabling the Default Loader

If you want to disable the default top-bar loader, add data-bladeflow-progress="false" to your layout's content wrapper element containing @bladeflowContent:

<main @bladeflowContent data-bladeflow-progress="false">
    @yield('content')
</main>

Custom Lifecycle Events

You can hook into BladeFlow's lifecycle events to build custom loading transitions, trackers, or UI animations:

bladeflow:start: Fired when a page transition begins (contains { url } in event.detail).
bladeflow:finish: Fired after the content, scripts, and styles have finished updating (contains { url } in event.detail).
bladeflow:error: Fired when a fetch request fails, right before falling back to full-page reload (contains { url, error } in event.detail).

Example: Custom Loading Spinner / Overlay

document.addEventListener('bladeflow:start', function (event) {
    console.log('Navigating to:', event.detail.url);
    // Show your custom loading overlay
});

document.addEventListener('bladeflow:finish', function (event) {
    console.log('Successfully navigated to:', event.detail.url);
    // Hide your custom loading overlay
});

document.addEventListener('bladeflow:error', function (event) {
    console.error('Failed to load page:', event.detail.url, event.detail.error);
    // Hide loader
});

Requirements

PHP 8.1+
Laravel 10, 11, 12, or 13

Contributing

Found a bug or want to improve something? PRs are welcome on GitHub.

License

MIT — Tanvir Hossen Bappy

thbappy7706/bladeflow

包简介

README 文档

README

Quick Start

Setup — `@extends` / `@section`

Setup — `x-layout` components

What works out of the box

Progress Indicator & Lifecycle Events

Disabling the Default Loader

Custom Lifecycle Events

Example: Custom Loading Spinner / Overlay

Requirements

Contributing

License

统计信息

GitHub 信息

其他信息

承接程序开发

thbappy7706/bladeflow

包简介

README 文档

README

Quick Start

Setup — @extends / @section

Setup — x-layout components

What works out of the box

Progress Indicator & Lifecycle Events

Disabling the Default Loader

Custom Lifecycle Events

Example: Custom Loading Spinner / Overlay

Requirements

Contributing

License

统计信息

GitHub 信息

其他信息

承接程序开发

Setup — `@extends` / `@section`

Setup — `x-layout` components