README

Inertia

Inertia.js server-side integration layer for Yii2
Server-driven pages, shared props, redirects, and asset version handling without jQuery

Features

Overview

yii2-extensions/inertia is the server-side base package for building modern Inertia-driven pages on top of Yii2. It does not ship a client adapter. Instead, it defines the server contract that future packages such as yii2-extensions/inertia-vue, yii2-extensions/inertia-react, and yii2-extensions/inertia-svelte can reuse.

Installation

composer require yii2-extensions/inertia:^0.1

Register the bootstrap class in your application configuration:

return [
    'bootstrap' => [\yii\inertia\Bootstrap::class],
];

Quick start

Render a page directly from a controller action:

use yii\inertia\Inertia;
use yii\web\Controller;
use yii\web\Response;

final class SiteController extends Controller
{
    public function actionIndex(): Response
    {
        return Inertia::render(
            'Dashboard',
            ['stats' => ['visits' => 42]],
        );
    }
}

Or extend the convenience controller:

use yii\inertia\web\Controller;
use yii\web\Response;

final class SiteController extends Controller
{
    public function actionIndex(): Response
    {
        return $this->inertia(
            'Dashboard',
            [
                'stats' => ['visits' => 42],
            ]
        );
    }
}

Or inject the renderer contract. Bootstrap binds ResponseRendererInterface to InertiaRenderer in the DI container, so the action stays decoupled from the Inertia implementation and overlays (Inertia, JSON, API) can swap the renderer without rewriting controller code:

use yii\inertia\web\ResponseRendererInterface;
use yii\web\{Controller, Response};

final class SiteController extends Controller
{
    public function __construct(
        $id,
        $module,
        private readonly ResponseRendererInterface $renderer,
        $config = [],
    ) {
        parent::__construct($id, $module, $config);
    }

    public function actionIndex(): Response|string
    {
        return $this->renderer->render('Dashboard', ['stats' => ['visits' => 42]]);
    }
}

Configuration example

use yii\inertia\Manager;

return [
    'bootstrap' => [\yii\inertia\Bootstrap::class],
    'components' => [
        'inertia' => [
            'class' => Manager::class,
            'id' => 'app',
            'rootView' => '@app/views/layouts/inertia.php',
            'version' => static function (): string {
                $path = dirname(__DIR__) . '/public/build/manifest.json';

                return is_file($path) ? (string) filemtime($path) : '';
            },
            'shared' => ['app.name' => static fn(): string => Yii::$app->name],
        ],
    ],
];

Dev server support (Vite)

The bundled \yii\inertia\Vite helper component renders asset tags for both development and production. When devMode is true, it emits @vite/client plus each configured entrypoint from devServerUrl, enabling Vite's HMR WebSocket end-to-end. When devMode is false, it reads the manifest at manifestPath and renders hashed asset tags for production.

Typical development flow: run npm run dev to start the Vite dev server and launch Yii2 with a dev environment flag (for example, YII_ENV=dev ./yii serve). YII_ENV does not toggle Vite::$devMode on its own; your application configuration must wire the two together, for example:

'components' => [
    'inertiaVite' => [
        'class' => \yii\inertia\Vite::class,
        'devMode' => YII_ENV === 'dev',
        // ...
    ],
],

For framework-specific setup, see:

• yii2-extensions/inertia-react — React Refresh preamble auto-injection.
• yii2-extensions/inertia-vue — Vue HMR (no extra preamble).

Prop types (v3)

The package supports the Inertia v3 prop types for fine-grained control over when and how props are resolved:

use yii\inertia\Inertia;

return Inertia::render(
    'Dashboard',
    [
        'stats' => $stats,                                              // regular prop
        'users' => Inertia::defer(fn () => User::find()->all()),        // loaded after render
        'activity' => Inertia::optional(fn () => $user->getActivity()), // only on partial reload
        'auth' => Inertia::always(fn () => ['user' => $identity]),      // always included
        'items' => Inertia::merge($paginated)->append('data', 'id'),    // merge instead of replace
        'countries' => Inertia::once(fn () => Country::find()->all()),  // resolved once, cached
    ],
);

See the Usage Examples for detailed documentation on each prop type.

Validation and flash messages

This package maps the session flash key errors to props.errors and exposes all remaining flashes at the top-level flash page key. A typical validation redirect looks like this:

if (!$model->validate()) {
    Yii::$app->session->setFlash('errors', $model->getErrors());

    return $this->redirect(['create']);
}

Yii::$app->session->setFlash('success', 'Record created.');

return $this->redirect(['view', 'id' => $model->id]);

CSRF protection

Drop in yii\inertia\web\Request to enable Inertia's automatic cookie-to-header CSRF flow:

'request' => [
    'class' => \yii\inertia\web\Request::class,
    'cookieValidationKey' => 'your-secret-key',
],

Inertia's HTTP client reads the XSRF-TOKEN cookie and sends it as X-XSRF-TOKEN automatically no client-side configuration required. See the Configuration Reference for details.

Package boundaries

This repository intentionally does not include Vue, React, or Svelte bootstrapping. Those concerns belong in separate client adapter packages built on top of the server contract defined here.

Documentation

For detailed configuration options and advanced usage.

• 📚 Installation Guide
• ⚙️ Configuration Reference
• 💡 Usage Examples
• 🧪 Testing Guide

Package information

Quality code

License