Getting Started

Install with Composer and confirm the package supports your Laravel/PHP version. Release 1.1.3 adds PHP 8.3 support, so PHP 8.3 projects can use it without treating it as an unsupported runtime.
Check whether the package’s service provider is auto-discovered. If not, register it manually in config/app.php or bootstrap/providers.php depending on your Laravel version.
Publish the package config first, then open the config file and verify the root template value against the actual Blade file you use for Inertia responses. Release 1.1.3 fixes a docs/default-config divergence here, so do not assume old examples match the current published config.
First use case: wire one Laravel route/controller to render an Inertia page, confirm the configured root Blade template loads, and verify the page receives props. This validates installation, config publishing, root-template resolution, and frontend mounting in one pass.

Implementation Patterns

Treat the published config as the source of truth. Set the root template explicitly rather than relying on an inherited default, especially across local, CI, and production environments.
Keep root-template setup close to the controller pattern: a controller returns the Inertia response, the package resolves the configured root template, and the Blade template contains the Inertia mount point and asset directives.
Use a single shared root template for typical pages unless you have a deliberate need for separate templates. This keeps layout, asset loading, and shared meta tags consistent.
In tests, assert both the Inertia response and the resolved root view. This catches config drift that ordinary HTTP status assertions miss.
For upgrades, run the package test suite against PHP 8.3 if that is your target runtime, and verify Composer constraints for Laravel, PHP, and frontend tooling.
In CI, include a job that clears and rebuilds config caches before running tests so root-template and package-config behavior matches production.
For multi-environment setups, keep environment-specific root-template overrides in .env or deployment config only when necessary; otherwise keep one explicit template to avoid docs/config mismatches.

Root-template mismatches are the first thing to debug for blank pages, missing Inertia mounts, or “view not found” errors. Check the package config value, the Blade file path, and Laravel’s view cache.
After changing package config, run php artisan config:clear locally and rebuild config cache in production. Stale cached config can make 1.1.3’s fix appear not to work.
If you previously copied the documented root-template value, compare it with the current default config after upgrading. The 1.1.3 fix means old examples may no longer represent the intended default.
PHP 8.3 support does not automatically mean every transitive dependency is compatible. Verify Composer platform requirements and run the application test suite on 8.3 before deploying.
When publishing config during an upgrade, diff rather than overwrite. Publishing can replace local customizations such as a custom root template or package-specific options.
Use Laravel’s config cache and route cache checks when behavior differs between local and production. Clear caches after package upgrades.
Extension points to inspect first: published config, root-template override, service-provider registration, and any middleware or shared-prop integration the package exposes. Prefer these over editing vendor files.
No breaking changes are called out in 1.1.3, but it is still worth checking the package’s changelog and Composer constraints before a broad upgrade.