Download the PHP package monoeq/kirby-inertia without Composer

Kirby Inertia

Inertia.js adapter for Kirby 3.

Inertia allows you to build your front end using Javascript (React, Vue and Svelte), while letting the server (in this case, Kirby) take care of routing and shaping data. Think of it as building a normal Kirby site, but the front end is rendered with Javascript.

How it works

The basic idea is when loading your site in the browser, Kirby serves up an HTML page with the page data inlined as JSON so your Javascript application can render the page. As you navigate to different pages, requests are sent to Kirby with an X-Inertia header, informing Kirby to return only the JSON for the page, rather than a full HTML response. Your Javascript application picks up on this data and renders each new page. You can read a bit more about how it works on the Inertia site.

📌 This readme does not cover how Inertia works, or how to build your front-end. It just outlines the core features implemented to use Kirby as an Inertia backend.

Setup

After installation, the bare minimum you need to do is define a default.php template:

The included inertia snippet simply renders an application shell with the current page data encoded as JSON:

At this point you can go ahead and build your Inertia front end. If you visit your site in the browser (and view source), you’ll see the application shell with page data inlined. If you were to request that same url with an X-Inertia header (test using wget/curl or Postman), a JSON response will be returned instead.

Creating Responses

Inertia responses in Kirby are created with Kirby Controllers. The only difference with a typical Kirby controller is you return an Inertia::render function, instead of an array. This plugin assigns a default.php controller for you:

The first argument specifies the name of the view your Javascript application should render, the second argument is the page data. In this case we’re using the $page->intendedTemplate() as the view name, and the $page->toArray() method to pass the page data.

Here's an example Controller with more specific control:

Inertia Features

The following sections outline how to use some of Inertia's features in Kirby since they differ slightly with the Laravel adapter.

Lazy evaluation

Lazy evaluation and partial data works as expected, just wrap your data in closures:

Shared Data

Unlike the Laravel adapter, Shared Data in Kirby is defined in your config.php. You can define shared data as an array (values can be closures) or as a closure which returns an array:

Form Handling

Handle forms in your Kirby controller like you usually would. Just make sure you redirect to a view as explained in the Inertia docs:

Error Handling

You'll want to handle errors in the controller as well. An See an example here.

Root template data

You can access data in your Kirby templates with the via the $inertia variable. Example: $inertia['prop']

With View Data

Kirby Inertia does not have a withViewData method, instead, you can optionally pass a 3rd param into Inertia::render. This just passes data into the kirby template like the normal controller behavior.

Session Data

An flash messages, and is similar to Laravel's Inertia::share. You can handle your Inertia session data when you set up your shared data in config.php:

So you can imagine in a form controller, using this helper like so:

From there, in your Javascript views you can pick up on this data

Config

Setup versioning and shared data in your config.php.

Classes API

Inertia

Inertia::render($name, $data, $viewData)

Return from your Kirby Controllers to render an Inertia response.

InertiaSession

Wrapper class around kirby()->session() for passing data to your Inertia views. Data is namespaced under the hood with inertia to avoid conflict with other Kirby session data.

InertiaSession::set($key, $value)

Wrapper around $session->set()

InertiaSession::append($key, $value)

Appends (or sets if not yet defined) value to the desired key.

InertiaSession::merge($key, $value)

Merges (or sets if not yet defined) value to the desired key.

InertiaSession::get($key)

Wrapper around $session->get()

InertiaSession::pull($key)

Wrapper around $session->pull()

InertiaSession::remove($key)

Wrapper around $session->remove()

Installation

Download

Download and copy this repository to /site/plugins/kirby-inertia.

Git submodule

Composer

Other Notes

Auto Templates

Typically in Kirby you need to create an actual template file for a controller to be called. But when using Inertia you usually only need the default.php template. As a helper, this plugin automatically assigns any controller file which does not have a matching template file to default.php, allowing you to just create controllers without worrying about creating templates.

Example Front End

Refer to the Inertia.js docs for how to build an Inertia front end, but here's a bare minimum example using Vue:

app.js

templates/default.vue

Todo

• [ ] Caching
  • Enabling the Kirby cache will currently break Inertia functionality.

Credits

• Jon Gacnik