Building an Adapter

Inertia speaks plain HTTP and JSON, so you may bring it to any server-side framework by writing an adapter that implements the Inertia protocol. Before you start, check the community adapters to see whether your framework already has one. This page outlines how an adapter is structured and which practices to follow, while the protocol specifies every header and field mentioned here.

The Reference Implementation

The official Laravel adapter is the reference implementation of the protocol, and every example in this documentation uses it. Where the protocol leaves a choice to the server, follow the Laravel adapter unless your framework has a strong reason to differ.

Concern	Laravel Source
Rendering responses	`Response.php`, `ResponseFactory.php`
Resolving props	`PropsResolver.php`
Middleware	`Middleware.php`
Root template	`View/Components/App.php`, `View/Components/Head.php`
Server-side rendering	`Ssr/HttpGateway.php`
Testing helpers	`Testing/AssertableInertia.php`

The adapter’s test suite covers edge cases that the protocol describes only briefly, so porting the relevant tests is a quick way to confirm that your adapter behaves the same way.

The Basics

A basic Inertia application needs a render function, a root template helper, and a middleware from your adapter. The render function accepts a component name and props, builds the page object, and returns either an HTML response or an Inertia response. A minimal version looks like this.

public function toResponse($request)
{
    $page = [
        'component' => $this->component,
        'props' => array_merge($this->sharedProps, $this->props),
        'url' => $request->getRequestUri(),
        'version' => $this->version,
    ];

    if ($request->header('X-Inertia')) {
        return new JsonResponse($page, 200, ['X-Inertia' => 'true']);
    }

    return view($this->rootView, ['page' => $page]);
}

Prop types such as deferred and merge props add their own metadata fields to the page object. You may add those later. The root template helper renders the page object script and the root element into the application’s layout, like the Laravel adapter’s <x-inertia::app> and <x-inertia::head> Blade components. These helpers also print the output of server-side rendering. The middleware handles most cross-cutting protocol behavior. The Laravel adapter’s Middleware::handle() method does the following:

Sets the Vary: X-Inertia header on every response.
Returns a 409 on an asset version mismatch for Inertia GET requests.
Converts a 302 redirect after a PUT, PATCH, DELETE, or QUERY request into a 303.
Converts a redirect to a URL fragment into an X-Inertia-Redirect response.
Redirects back when a controller returns an empty 200 OK response.
Reflashes the session’s flash data on redirects and version mismatches.
Registers shared data, including the validation errors from the session.

Your adapter also needs to handle partial reloads. Apply the partial reload filters before invoking any prop closures, so excluded props never run their queries.

Verifying Your Adapter

Unit tests confirm that your adapter emits the right headers and page objects, but not that the official client accepts them. Build a small application with one of the official client-side adapters and check the following:

The first page load renders the page component.
Clicking a <Link> swaps the component without a full page reload.
Submitting a form with invalid data redirects back and shows the validation errors.
A partial reload returns only the requested props and the errors prop.
Changing the asset version makes the next visit reload the full page.

For broader coverage, you may port the controllers of the demo application to your framework and run its Vue frontend against your adapter. Its pages cover most of the features in this documentation, including forms, prefetching, deferred props, and error handling.

Additional Features

Once the basics work, you may add any of the following features.

Feature	Laravel API	Specification
Optional and deferred props	`Inertia::optional()`, `Inertia::defer()`	Deferred and optional props
Always props	`Inertia::always()`	Always props
Rescued deferred props	`Inertia::defer(..., rescue: true)`	Rescued deferred props
Merge props	`Inertia::merge()`, `Inertia::deepMerge()`	Merging props
Once props	`Inertia::once()`	Once props
Infinite scroll	`Inertia::scroll()`	Infinite scroll
Live props	`Inertia::live()`	Live props
External redirects	`Inertia::location()`	Redirects
Flash data	`Inertia::flash()`	The page object
History encryption	`Inertia::encryptHistory()`	The page object
Server-side rendering		Server-side rendering
Big integers	`preserveBigIntegers()`	The page object
Precognition		Request headers
Testing helpers	`assertInertia()`	Testing
DevTools		DevTools protocol

Best Practices

Follow Your Framework’s Conventions

Follow your framework’s naming, configuration style, and extension points, so a Rails adapter reads like Rails and a Django adapter reads like Django. Keep the concepts close to the Laravel adapter’s, such as render, share, defer, and merge, so this documentation stays useful to your users.

Build Both Responses From One Code Path

Build the page object for the HTML document and for the JSON response in one code path. Any difference between the two causes bugs that appear only on the first visit or only after navigation.

Compose Prop Types

A single prop may be both deferred and mergeable, or once and deferred. Modeling each behavior as an independent flag or trait, rather than as one class per combination, keeps these combinations simple.

Encode Empty Errors as Objects

Encode the errors prop and each error bag as JSON objects, even when they are empty. Languages that use one type for lists and maps, such as PHP, encode an empty one as [] by default, but the protocol expects {}.

Render Error Pages Through Inertia

Exceptions such as 404 and 500 errors are often rendered outside your middleware, so they lose shared data. Provide a way to render them as Inertia responses with the middleware’s shared data, like the Laravel adapter’s Inertia::handleExceptionsUsing() method.

Run Post-Response Work for Client Redirects

A 409 for an external redirect or a fragment redirect is a successful request, because the client completes the navigation. Some frameworks skip post-response work, such as after-response callbacks, for 4xx statuses, so make sure your adapter still runs it for these responses.

Document Your Coverage

Users assume that every feature in this documentation works with your adapter. State which Inertia version your adapter targets and which protocol features it implements, and review the Laravel adapter’s releases to keep it current. Once your adapter is ready, you may list it on the community adapters page.

Getting Started

Installation

Core Concepts

The Basics

Data & Props

Security

Advanced

Server Adapters

The Reference Implementation

The Basics

Verifying Your Adapter

Additional Features

Best Practices

Follow Your Framework’s Conventions

Build Both Responses From One Code Path

Compose Prop Types

Encode Empty Errors as Objects

Render Error Pages Through Inertia

Run Post-Response Work for Client Redirects

Document Your Coverage

​The Reference Implementation

​The Basics

​Verifying Your Adapter

​Additional Features

​Best Practices

​Follow Your Framework’s Conventions

​Build Both Responses From One Code Path

​Compose Prop Types

​Encode Empty Errors as Objects

​Render Error Pages Through Inertia

​Run Post-Response Work for Client Redirects

​Document Your Coverage

The Reference Implementation

The Basics

Verifying Your Adapter

Additional Features

Best Practices

Follow Your Framework’s Conventions

Build Both Responses From One Code Path

Compose Prop Types

Encode Empty Errors as Objects

Render Error Pages Through Inertia

Run Post-Response Work for Client Redirects

Document Your Coverage