README

composer require splitstack/inertia-split

Serve Inertia and JSON from the same Laravel controller — no branching logic, no duplicate routes, no separate API layer.

inertia-split

Hybrid responses

Design endpoints that deliberately serve both an Inertia SPA and an API consumer from the same action. SplitResponseBuilder handles the branching so your controller doesn't have to.

use Splitstack\InertiaSplit\Split\Concerns\HasHybridResponses;

class ProductController extends Controller
{
    use HasHybridResponses;

    public function index()
    {
        return $this->respond(Product::paginate())
            ->component('Products/Index');
    }

    public function store(StoreProductRequest $request)
    {
        Product::create($request->validated());

        return $this->respond()->route('products.index');
    }
}

->component() renders an Inertia component for SPA requests and returns JSON for API requests. ->route() issues an Inertia client-side redirect for SPA requests. Chain exactly one — specifying both or neither throws.

Alternatives to the trait:

Extend HybridController to skip the use declaration:

use Splitstack\InertiaSplit\Split\Controllers\HybridController;

class ProductController extends HybridController { ... }

Or use the Split facade from anywhere:

use Split;

return Split::respond($data)->component('Products/Index');

Incremental migration from an existing API

Already have a working Laravel API and want to adopt Inertia without a rewrite? Annotate a method and leave the body alone. When an Inertia request comes in, response()->json() renders the component instead. When an API client hits the same endpoint, it gets plain JSON back. The controller doesn't know the difference.

use Splitstack\InertiaSplit\Migration\Attributes\InertiaComponent;

class UserController extends Controller
{
    #[InertiaComponent('Users/Index')]
    public function index()
    {
        return response()->json(User::paginate()); // untouched
    }

    #[InertiaComponent('Users/Show', layout: 'admin')]
    public function show(User $user)
    {
        return response()->json($user); // untouched
    }

    public function store(Request $request) // no attribute = always JSON
    {
        return response()->json(User::create($request->validated()), 201);
    }
}

Annotate methods as you build out the frontend. Everything else keeps working.

Setup: Register the factory override in your AppServiceProvider. Explicit opt-in — nothing changes until you do this.

use Illuminate\Contracts\Routing\ResponseFactory;
use Splitstack\InertiaSplit\Migration\Http\HybridResponseFactory;

public function register(): void
{
    $this->app->singleton(ResponseFactory::class, HybridResponseFactory::class);
}

How it works: HybridResponseFactory checks the current route action for #[InertiaComponent]. If the attribute is present and the request carries an X-Inertia header, it renders the component with your data as props. Otherwise it falls through to normal JSON. Methods without the attribute are completely unaffected.

Browser visits: an Inertia visit (X-Inertia header) always renders the component, and a client that explicitly asks for JSON (Accept: application/json) always gets JSON. The one ambiguous case is a plain browser visit to the URL. By default that returns JSON, so nothing changes until your frontend is ready. Mark a route as browsable to render the Inertia page for those visits too:

#[InertiaComponent('Users/Index', browsable: true)]
public function index()
{
    return response()->json(User::paginate());
}

Set the default for every annotated route with the browsable config option (see below); the attribute overrides the config per route.

Configuration

Publish the config file:

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

This writes config/split.php:

return [
    // Should a plain browser visit to an annotated route render the Inertia
    // page? Inertia visits and explicit JSON clients are unaffected. Individual
    // routes can override this via #[InertiaComponent(browsable: ...)].
    'browsable' => false,
];

Setting	Default	Effect
`browsable`	`false`	`true` renders the Inertia page for a plain browser visit; `false` returns JSON.

Requirements


PHP	^8.2
Laravel	11 · 12 · 13
inertiajs/inertia-laravel	^2.0

License

MIT

splitstack / inertia-split

Package info

Security

Statistics