README

Yii Framework

Inertia.js + Vue 3 Application Template

Reference Yii 3 application with Inertia.js + Vue 3 integration
Server-driven SPA with TypeScript, Vite 8, persistent dark mode, and browser-level tests
Yii owns routing and page data, Inertia carries navigation state, and Vue renders the interface

Features

Architecture presents a constructor-injected invokable action and the explicit PSR-15 middleware pipeline that handles each request.
Stack shows the Yii, Inertia, Vue, and Vite responsibilities in one server-driven request flow.
Partial reloads refresh only the runtime page prop while preserving the persistent layout, deferred data, and scroll position.
Deferred props resolve the ecosystem diagnostics group after the first response, with an accessible loading state in Vue.
Infinite scroll exposes requestFeed through Prop::scroll(). The server provides cursor metadata, Inertia merges requestFeed.data, and Vue appends each three-event page inside a contained scroll region.
Persistent theme follows the operating-system light and dark preference until the visitor chooses a mode, then stores that choice locally.

Requirements

PHP 8.3 or later.
Composer 2.
Node.js 22.12 or later.

Quick start

# create a new Yii 3 application using the Inertia.js + Vue 3 template
composer create-project --prefer-dist yii3/app-inertia-vue:^0.1@dev app-vue

# navigate to the application directory
cd app-vue

# install the locked Node.js dependencies
npm ci

# build production assets (one-shot; for live editing see the HMR workflow below)
npm run build

# start the development server on port 8081
APP_ENV=debug APP_DEBUG=true ./yii serve

Open http://localhost:8081.

Development workflow with HMR

npm run build produces production assets once and exits. To edit .vue files and see changes in the browser without rebuilding, run two processes side by side:

# Terminal 1 — Vite dev server (HMR for .vue and the application stylesheet)
npm run dev

# Terminal 2 — Yii 3 in dev mode
APP_ENV=dev APP_DEBUG=true ./yii serve

How the pieces connect:

The PHP application continues to own routing and the initial HTML response.
config/params.php reads the APP_ENV environment variable. When it equals dev, the framework-agnostic Vite facade is built with DevelopmentConfiguration, and the root view emits <script> tags pointing at http://127.0.0.1:5173 instead of the built manifest. Every other environment uses ProductionConfiguration, where PHPForge\Vite\Vite owns loading and caching public/build/.vite/manifest.json.
Vue HMR is carried natively by @vite/client together with @vitejs/plugin-vue; no additional preamble is required.
The manifest's SHA-256 hash provides the Inertia asset version, so clients reload after built asset references change.
Before deploying, stop the Vite dev server, run npm run build, and set APP_ENV to prod, then serve public/.

For manifest options, development-server behavior, and CORS configuration, see the php-forge/vite documentation.

Debugger

yii3/debug is a development dependency. The package contributes its toolbar to the application's yiisoft/middleware-dispatcher parameters without an application middleware reference to the debugger. The application explicitly composes the Inertia collector, panel, and page observer with the Vite collector and panel in its debug, dev, and test environments. Production keeps that integration absent without runtime package detection.

The package owns the local-only /debug, /debug/view, /debug/php-info, and /debug/toolbar routes and their Yii IP filtering. A captured Inertia response adds an Inertia chip linked to its component, page metadata, props, negotiation headers, and redacted raw payload. Vite adds its runtime mode and exposes normalized configuration and production manifest chunks.

Project map

config/routes.php                 Named Yii 3 routes
config/di/application.php         Application and Vite DI definitions
config/environments/debug/        Explicit non-production debugger integration
config/params.php                 Vite, middleware, Inertia, and application parameters
public/index.php                  Dotenv and HTTP application bootstrap
resources/js/app.ts               Typed Inertia and Vue bootstrap
resources/js/composables/         Persistent theme state
resources/js/layouts/             Persistent Vue application shell
resources/js/pages/Home.vue       Home page and Inertia demonstrations
resources/js/styles/app.css       Application visual system
resources/views/app.php           Initial Inertia HTML document
src/Web/Workbench/HomeAction.php  Home props and scroll pagination
tests/Web/                        Essential browser-level application tests

Quality checks

npm run typecheck
npm run build
composer tests
composer static
composer check-dependencies
vendor/bin/ecs check --ansi

PHPStan runs at maximum level. Use composer ecs when you intentionally want to apply coding-standard fixes. The Web suite covers the home page, its feed pagination, and the application-owned 404 response without duplicating tests for framework or tooling packages.