Create server-side-rendered SPAs with Kirby and Inertia.js. This plugin configures your Kirby site to output Inertia responses and integrates the server-side-renderer for Inertia.
Inertia is a new approach to building classic server-driven web apps. It works similar to the backend architecture for Kirby's Panel - but built with an ecosystem around it that works with Vue, React and Svelte.
Raw JSON data is returned from the server and rendered on the client-side. This allows you to build SPAs without having to build a separate API. Utilizing the server-side renderer, this makes perfect for websites that are heavily interactive but shouldn't suffer from SEO or performance issues.
I recommend using Vite & kirby-laravel-vite for compiling your frontend assets. It's the best way to get started with a powerful build setup without having to worry too much about the configuration.
To get started with Inertia, simply install the plugin using composer (composer require tobimori/kirby-inertia
) and setup your default.php
template to include the Inertia response:
<!DOCTYPE html>
<html>
<head>
<?php /* other meta tags */ ?>
<?php /* kirby-laravel-vite */ ?>
<?= vite()->reactRefresh() ?>
<?= vite(['src/index.tsx', 'src/styles/index.css']) ?>
<?= inertiaHead() ?> <?php /* for server-side-rendered head */ ?>
</head>
<body>
<?= inertia() ?> <?php /* renders the application shell or server-side-rendered content */ ?>
</body>
</html>
You can then get started building your Inertia frontend.
We're creating Inertia responses inside Kirby controllers. You can use the Inertia::createResponse()
method to correctly format the response.
The default controller simply runs the toArray()
methods on the Pages. You can override this by creating a custom controller for your page templates.
<?php
use Kirby\Cms\Page;
use tobimori\Inertia\Inertia;
return function (Page $page) {
return Inertia::createResponse(
$page->intendedTemplate(), // the component name passed to inertia
$page->toArray() // the props passed to the component
);
};
If you need to access any additional data in the Kirby template, you can pass it on by returning an array as the third argument.
Inertia allows partial requesting of data from the server. In that case, if you're running resource-heavy operations in your controller, you might want to delay them until they're actually needed. You can do this by utilizing Kirby's LazyValue
class as props.
Inertia::createResponse(
'page',
[
'title' => $page->title(), // will be evaluated immediately
'children' => new LazyValue(function () use ($page) { // will be evaluated when requested
return $page->children()->listed();
})
]
);
Shared data can be defined anywhere in your application before the first inertia()
or inertiaHead()
call in the template.
You can use the Inertia::share()
method to define shared data.
Inertia::share('user', kirby()->user()->id());
You can also use the config option tobimori.inertia.shared
to define shared data in your site/config/config.php
file.
// site/config/config.php
return [
'tobimori.inertia.shared' => [
'user' => new LazyValue(function () { // lazy evaluation works here as well
return kirby()->user()->id();
})
]
];
Keep in mind that you can't access the Kirby instance in the config file, so we're using the LazyValue
class here.
Inertia allows you to render your application on the server-side. This is especially useful for SEO and performance reasons.
To enable server-side rendering, you need to set the tobimori.inertia.ssr.enabled
config option to true
.
// site/config/config.php
return [
'tobimori.inertia.ssr' => [
'enabled' => true,
'server' => 'http://127.0.0.1:13714'
],
];
You'll also have to specify the URL of the server-side renderer.
Kirby Inertia doesn't provide a command to start the server-side renderer like the Laravel package, you'll have to implement that yourself using a process manager like PM2.
If you want to use custom routes for your Inertia application (e.g. when data is defined in the component), you can use the Inertia::route()
helper to define a custom route in your site/config/config.php
file.
// site/config/config.php
return [
'routes' => [
Inertia::route('about', 'about') // renders the about component on /about
]
];
Support for Kirby caching is currently WIP, stuff might not work with the pages cache enabled.
This plugin automatically assigns the default template to all pages with a controller that don't have a template assigned. This is necessary so Kirby picks up the correct controller.
Parts of this plugin are based on an older Inertia implementation without server-side rendering support by Jon Gacnik.
MIT License © 2023-2024 Tobias Möritz