Inertia.js Craft CMS Adapter

This is a server-side adapter for Inertia built with Craft CMS workflow simplicity in mind.

It utilizes Craft's routing, as well as Twig for crafting Inertia responses, rather than requiring they be written directly in PHP (as a traditional Inertia application does).

Demo project

Installation

Install via Composer:

composer require rareform/craft-inertia
php craft plugin/install inertia

Be sure to follow the installation instructions for the client-side framework you use.

Required Reading

The Inertia documentation is a must-read to understand the protocol, the responsibilities of this adapter, and how to use Inertia on the client-side. The following sections will explain how to use this adapter, but assume you have a basic understanding of Inertia.

Defining Pages

Every page in your javascript application is backed by a Twig template which returns a page object. The page object defines which page component to render, and what prop data is received.

{# templates/posts/index.twig #}

{% set posts = craft.entries.section('posts').limit(20).all() | map(post => {
    title: post.title,
    body: post.body
}) %}

{# Use the inertia variable to define the Page component to render and props to pass #}
{{ inertia('Posts/Index', { posts: posts }) }}

Note: templates are passed element variables automatically when a request is matched to an element. If you want to pass the element as a prop automatically to your page component, set the injectElementAsProp configuration to true.

Shared Data

Shared data will automatically be passed as props to your application, sparing you the cumbersome tasks of redefining the same prop data in every page response.

Create a shared.twig at the root of your /templates directory, and use the inertiaShare variable:

{# templates/shared.twig #}

{% set sharedProps = {
   flashes: craft.app.session.getAllFlashes(true),
   csrfTokenValue: craft.app.request.csrfToken,
   csrfTokenName: craft.app.config.general.csrfTokenName
} %}

{% if currentUser %}
  {% set user = {
    id: currentUser.id,
    fullName: currentUser.fullName,
    email: currentUser.email,
  } %}
  {% set sharedProps = sharedProps|merge({currentUser: user}) %}
{% endif %}

{{ inertiaShare(shareProps) }}

Saving Data

Craft CMS does not use traditional POST, PUT, PATCH, and DELETE requests for saving data, and instead uses the action parameter to hit various internal Craft controllers. This means saving data to Craft CMS data is a little different than what is expected in a traditional Inertia application.

const form = useForm({
  sectionId: 1,
  typeId: 2,
  CRAFT_CSRF_TOKEN: csrf.value,
  action: "entries/save-entry",
  title: "My New Post",
  fields: {
    customField: "My Custom Field Value",
  },
});

const saveEntry = () => {
  // Don't specify a POST url, as we're using the action parameter
  form.post("", {
    // Force the request to use form data in order for Craft to process the request
    forceFormData: true,
  });
};

We hope to simplify this boilerplate for saving data by final 1.0.0 release.

Configuration

Create an inertia.php file in your Craft /config directory. Shown are the default values:

<?php

return [
    // The root template that will be rendered when first loading your Inertia app
    // (https://inertiajs.com/the-protocol#html-responses).
    // Includes the div the inertia app will be rendered to:
    // `<div id="app" data-page="{{ page|json_encode }}"></div>`
    // and calls the Inertia app `<script src="<path_to_app>/app.js"></script>`
    'view' => 'base.twig',

    // Whether inertia's assets versioning shall be used
    // (https://inertiajs.com/the-protocol#asset-versioning)
    'useVersioning' => true,

    // Array of directories that will be checked for changed assets if `useVersioning` => true
    'assetsDirs' => [
        '@webroot/dist/assets'
    ],

    // Whether to inject the element matched from routing automatically into the application
    'injectElementAsProp' => false,

    // Whether all routes will be Inertia responses
    'takeoverRouting' => true,
];

Requirements

This plugin requires Craft CMS 5.4.0 or later, and PHP 8.2 or later.

Installation

You can install this plugin from the Plugin Store or with Composer.

From the Plugin Store

Go to the Plugin Store in your project’s Control Panel and search for “Inertia”. Then press “Install”.

With Composer

Open your terminal and run the following commands:

# go to the project directory
cd /path/to/my-project.test

# tell Composer to load the plugin
composer require rareform/craft-inertia

# tell Craft to install the plugin
./craft plugin/install inertia