robuust / craft-inertia
Opt-in public Inertia frontend integration for Craft CMS 6.
Requires
- php: ^8.5
- craftcms/cms: ^6.0.0-beta.1
- inertiajs/inertia-laravel: ^3.7
- laravel/framework: ^13.38
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 15:04:07 UTC
README
Render Craft CMS 6 entries as Vue pages with Inertia.js while keeping Craft’s native URLs and previews.
Overview
Build your Craft CMS 6 frontend with Inertia.js and Vue while keeping Craft’s native content editing, URLs, multisite routing, and previews. The Craft Inertia plugin connects selected Craft entries to your Vue pages and passes their content directly to the components that render them.
Turn a Craft entry into a Vue page
Set a section’s Template to inertia:Site/Home to render it with your
Site/Home.vue component. Craft resolves the URL, current site, and matching
entry using its normal publication and preview rules. The plugin then passes
the entry data to the official Inertia Laravel adapter.
Routing through Craft’s existing section settings lets you adopt Inertia one section at a time. Existing Twig and Blade pages and explicit routes can coexist with your Inertia pages.
Use your Craft fields directly in Vue
Read selected custom fields by handle, such as entry.fields.summary. Page
props include entry and site details, preview status, and the field data you
choose to send to the frontend. Configure selections for the main entry,
related entries, and Matrix blocks, and define responsive image variants for
asset fields. In 1.0.2, entries start with identity and empty fields until
you select fields for them.
Authorized previews use the draft or revision Craft resolved, so editors can see their changes in the Vue frontend before publishing.
Use Inertia navigation and optional server-side rendering
The first visit returns an HTML document. Navigation through an Inertia Link
loads the next page’s component and props as JSON, so Vue can update the page
without a full reload. You can enable server-side rendering for eligible public
requests so the first response already contains the rendered page.
Your project supplies its own Vue components, layouts, Blade root view, and Vite setup. The plugin also provides helpers for rendering page metadata, connecting native Craft forms to Inertia’s validation and flash handling, and rendering custom pages from your own controllers.
Requirements and guides
Craft Inertia 1.0 requires PHP ^8.5, Craft CMS ^6.0.0-beta.1, Laravel
^13.38, and the official Inertia Laravel adapter
(inertiajs/inertia-laravel ^3.7).
Quickstart · Installation · Upgrade · Compatibility
How it works
For a homepage mapped to inertia:Site/Home, the request flows through:
flowchart TD
A["Browser requests /"] --> B["Craft resolves the homepage entry and current site"]
B --> C["Template: inertia:Site/Home"]
C --> D["Plugin projects the entry and its fields"]
D --> E["Official Inertia adapter"]
E -->|"First visit"| F["HTML with SSR when configured and permitted"]
E -->|"Navigation via an Inertia Link"| G["JSON with component name and page props"]
F --> H["Site/Home.vue renders the page"]
G --> H
Loading
- Craft resolves the requested URL, current site and entry. It applies its normal publication and preview rules before the plugin selects a renderer.
- The plugin listens to Craft's native entry-routing event. A section template
such as
inertia:Site/Homeselects the Vue componentSite/Home. Explicit route/controller destinations keep precedence. - The plugin projects the actual matched entry into JSON-compatible page props.
In 1.0.2,
entryFieldsdetermines which custom fields are sent for the main entry, related entries and Matrix blocks. Authorized previews retain their matched draft/revision identity. - The plugin renders through the official Inertia Laravel adapter, using an isolated public response factory. It excludes CP/global shares and applies the configured root view, asset version, flash/error handling and response privacy policy.
- A first visit receives an HTML document and page data. When guest SSR is
configured and permitted, that HTML already contains the rendered Vue page.
Navigation through an Inertia
Linkreceives page JSON and updates Vue in the browser. Vue owns the page layout, components and interactions.
The main integration points are EntryTemplates, EntryProjection and EntryController, with the shared PublicRenderer for explicit project controllers.
| Owner | Responsibilities |
|---|---|
| Craft | Fields, entry types, sections, native URLs, sites, publication, preview identity and authorization. |
| This plugin | Opt-in entry rendering, field/link/image projection, generic Head rendering, public response isolation and Craft/Inertia policy. |
| Official Inertia adapters | HTML/page-JSON negotiation, client navigation, asset-version handling and SSR transport. |
| Consuming project | Vue pages and design, public Blade root, Vite builds, website queries, SEO content and runtime/deployment configuration. |
Install
When Craft Inertia is available in the Plugin Store, use the control panel installation guide.
Install the robuust/craft-inertia package from
Packagist in an existing
Craft 6 project that permits the Craft beta dependencies. Once 1.0.2 is
published, run the following commands for a new installation.
composer require 'robuust/craft-inertia:^1.0.2' --with-all-dependencies --no-interaction
php artisan craft:plugin:install craft-inertia --no-interaction
php artisan vendor:publish --tag=craft-inertia-config --no-interaction
No custom VCS repository or GitHub credentials are required. When migrating from a private VCS source, remove that repository entry and update the package lock. Craft discovers the plugin provider automatically. The package publishes its integration configuration; the consuming project supplies the frontend files.
The plugin uses the PHP namespace Robuust\CraftInertia and the native handle
craft-inertia. Use of the public source and Composer downloads is subject to
the Craft License.
Versions 1.0.0 and 1.0.1 include all layout fields whenever no field rule matches. Use the tagged 1.0.1 guide for that release, or see Installation for a pinned 1.0.2 candidate. For an existing installation, use the upgrade guide.
Configure the consuming project
The one-time host setup consists of:
| Location | Project configuration |
|---|---|
config/craft-inertia.php |
Select the public root view, for example frontend::app, and an explicit indexing policy when required. |
| Project service provider | Register the public view namespace and exclude native CP/action paths from the public SSR resolver. |
resources/views/app.blade.php |
Provide the HTML shell, Vite assets, <x-craft-inertia::head :page="$page" /> and <x-inertia::app />. |
resources/js/app.js |
Bootstrap the official Vue adapter with createInertiaApp(). |
resources/js/pages/ |
Supply the Vue components selected by section templates. |
vite.config.js and package.json |
Configure Vue and the official Inertia Vite plugin, and build the client and SSR bundles. |
| Project runtime | Configure SSR connectivity, a production SSR process when enabled, persistent asset storage and worker lifecycle. |
Set the published configuration to the project's public namespace:
return [ 'rootView' => 'frontend::app', 'indexingPolicy' => null, ];
For example, register the namespace and SSR exclusions in the project service
provider's boot() method. When cpTrigger is null, first configure Craft's
baseCpUrl with the dedicated control-panel origin, such as
https://cms.example.test. This lets the same setup distinguish CP requests
from the public website without a global /* exclusion:
use CraftCms\Cms\Cms; use CraftCms\Cms\Support\Url; use Illuminate\Support\Facades\View; use Inertia\Inertia; // Inside the project's service provider boot() method: View::addNamespace('frontend', resource_path('views')); $cpUrl = rtrim(Url::cpUrl(), '/'); $actionTrigger = trim(Cms::config()->actionTrigger, '/'); Inertia::withoutSsr([ $cpUrl, $cpUrl.'?*', $cpUrl.'/*', $actionTrigger, $actionTrigger.'/*', ]);
The namespace separates the public root from Craft's CP root. Keep the plugin's own provider under native Craft discovery; do not register it a second time.
The official @inertiajs/vite plugin can resolve pages and handle development
SSR from the normal application entry point. Cross-container development must
make its SSR endpoint reachable through the official inertia.ssr.hot_url
setting. Production uses the built SSR bundle and a separately supervised Node
process. SSR/protocol settings belong to inertia.*; integration settings belong
to craft-inertia.*. See INSTALLATION.md for the complete
host setup and the official SSR guide.
Native entry templates
Keep the section's native URI and select a Vue component in its Template:
| Content | Native URI | Template |
|---|---|---|
| Homepage single | __home__ |
inertia:Site/Home |
| Articles | articles/{slug} |
inertia:pages/articles/[slug] |
| Structure entry | Native nested URI | inertia:Site/Places/Show |
inertia:Site/Articles/Show resolves through the project's normal resolver,
for example resources/js/pages/Site/Articles/Show.vue. To expose summary
for entries of type article, add a rule in config/craft-inertia.php.
'entryFields' => [ 'article' => ['summary'], ],
Read the selected field under its native handle.
<p>{{ entry.fields.summary }}</p>
Craft's project config stores the section template and entry-type layout. Each
entry applies its own type rule, including entries from relation and Matrix
fields. A type rule takes precedence over '*'. An absent rule or an explicit
[] produces empty fields. Set '*' => '*' in 1.0.2 to deliberately expose
all layout fields for unmatched types. See the content contract
for field shapes and circular-reference handling.
| Page prop | Contents |
|---|---|
entry |
Native identity, title, URL, entry type and selected layout fields under fields. |
site |
Current site identity, language and base URL. |
preview |
Whether Craft supplied a preview entry. |
head |
Generic title/meta/link/JSON-LD and effective robots policy; no third-party plugin coupling. |
| Protocol props | Official adapter errors, flash and other protocol state. |
Assets retain list cardinality, even when a field allows one image. They include
the original URL, dimensions and alt text, with srcset: null. Select responsive
variants declaratively through fieldImageProfiles; the site chooses its image
profiles. Links use publication-aware URLs by default. Native HTML field data
uses its rendered representation. Table rows retain native column keys such as
col1 and col2. The generic head callback accepts project-calculated metadata;
packaged Vue/Blade Head components render it with consistent
robots policy, including without SSR. The plugin detects or imports no
third-party metadata plugin.
Ordinary mapped entry pages need no project entry controller, copied Laravel entry route, custom PHP renderer or per-page SSR middleware. Projects still own Vue/layout/build, search/navigation queries and business rules.
The exact inertia: prefix is opt-in. Explicit native route/controller
destinations take precedence. Twig/Blade, dynamic view routes, CP, actions,
API/feed endpoints and unknown paths retain native handling. No catch-all is
registered. An already configured project route remains ordinary Laravel code.
Bespoke project routes
Use Robuust\CraftInertia\Http\PublicRenderer for project controllers that select
their own props. It runs the same isolated response factory, SSR eligibility and
public protocol policy as the native entry renderer. Resolve props inside its
callback and use the supplied robots directive in project metadata:
use CraftCms\Cms\Entry\Elements\Entry; use CraftCms\Cms\Route\CurrentElement; use Illuminate\Http\Request; use Robuust\CraftInertia\Http\PublicRenderer; use Symfony\Component\HttpFoundation\Response; public function __invoke(Request $request, #[CurrentElement] Entry $entry): Response { return app(PublicRenderer::class)->render( $request, 'pages/work/[slug]', fn (string $robots): array => $this->pageProps($entry, $robots), $entry, ); }
The project owns pageProps(), including its selected content and SEO shape.
This API adds no automatic entry, site, preview or head props. The native
entry renderer supplies its standard projection. Components passed directly to
PublicRenderer use the host resolver; inertia: templates also accept bracketed
component segments such as pages/work/[slug]. Craft's actual matched live or
authorized preview entry is passed without requerying a canonical ID or slug. Missing entry context
and non-200 page statuses always disable public SSR and indexing.
The optional publicPagePolicy(Request, Entry): bool config callback can restrict
eligible pages or sections; it cannot allow authentication, preview, token or
form-state contexts. Existing indexingPolicy(Request): bool remains default
deny, and Craft's disallowRobots overrides it. Projects own their content
selection and authorization. See RENDERING.md
for controller, policy and error-response migration examples.
Keep web and craft context resolution before the controller. The shared
renderer runs the public Inertia middleware itself; do not wrap it in a second
Inertia protocol middleware. Native registered named/controller routes still
match their own URI/domain/method and retain other middleware. No catch-all or
routing listener is added for explicit controllers.
Existing manual integrations using HandleInertiaRequests and Inertia::render()
remain supported. Those integrations retain responsibility for their own share
isolation, guest SSR and indexing eligibility. The shared renderer centralizes
that boundary for selected project props and custom error pages.
Project-wide navigation/settings queries use the publicProps callback; global
Inertia::share() values remain excluded. Field selection, Assets profile
selection and generic Head metadata have declarative configuration, so ordinary
entry pages need no project controller or field serializer. See
public page extensions.
Rendering, privacy and lifecycle
Integration config belongs to craft-inertia.*. Official adapter SSR/protocol
config belongs only to inertia.*. Mapped pages use the project root and Vite
manifest version, private/no-store headers and Vary: X-Inertia. Indexing defaults
to deny; an explicit callable must return true, and Craft disallowRobots wins.
Private/auth/token/preview/form-state requests remain non-indexable and do not
reach SSR. Public guest SSR respects official configuration and host callbacks.
CP/global shared props are excluded from mapped pages; the host factory/gateway
are restored afterward. See RENDERING.md.
Native plugin disable/enable removes/restores the listener on a new boot,
including with cached routes. Restart long-lived workers after lifecycle changes.
The plugin does not rewrite section templates, DB state or project YAML.
Disabling an inertia:-only template leaves normal native template interpretation;
a working Twig/Blade fallback must be deliberately configured and retained.
There is no automatic reconstruction of a previous Twig design.
Installation covers native lifecycle and fallback.
FORMS.md covers the generic NativeForm::props($action, $redirect)
helper and native mutations/files. CONTACT_FORM.md shows
Contact Form as an optional project integration, using native validation events,
its existing action and the shared errors/flash bridge.
Planned extensions
These proposals extend the current integration. They are not implemented capabilities; the linked issues define their scope and acceptance criteria.
| Issue | Extension |
|---|---|
| #16 | TypeScript page props generated from Craft field layouts. |
Verification scope
This plugin contains no automated tests, fixtures or application harness. Its packaged Vue Head component uses the consuming project's frontend toolchain; the complete Vue application remains project-owned. Use Composer validation and PHP syntax checks for the package. Verify native URLs, field selection, preview identity, SSR/hydration, forms, privacy and fallback in the consuming project with its locked dependencies. See the compatibility matrix.
Earlier development reports and test sources remain available in Git history. They describe their original versions and bounded outcomes; they do not establish current compatibility or production acceptance.
Earlier integration work recorded four native account regressions and a nested Contact Form message issue. The inspected Contact Form 4.0.0 source contains the nested-message fix. Runtime acceptance of that release remains unverified. The 1.0 scope covers public entry pages, optional SSR, and native public forms. Full account flows and generated TypeScript props are deferred. See frontend requirements for the wider project scope.
Generic public project props, serializers and image profiles are documented in Public page extensions.