Inertiajs Laravel Package

Getting Started

This is a one-shot scaffolder, not a runtime dependency. You install it, run one Artisan command, and then you're living in the generated Inertia app — the package itself has no further role. Budget accordingly: "day-to-day" leverage here means the conventions the preset bakes in, not ongoing package usage.

Version note as of 0.4.0: Laravel 7 is now explicitly supported (that's the entire 0.4.0 changelog). If you're on Laravel 6, pin ^0.3; on Laravel 7, ^0.4. Nothing above Laravel 7 is supported, and 0.4.0 looks like the terminal release.

Minimal path on a matching app:

composer require laravel-frontend-presets/inertiajs:^0.4 --dev   # Laravel 7
# composer require laravel-frontend-presets/inertiajs:^0.3 --dev  # Laravel 6

php artisan ui inertiajs        # laravel/ui 2.x
# or, on laravel/ui 1.x / Laravel 6:
php artisan preset inertiajs

npm install && npm run dev
php artisan serve

Check the package's src/ for the exact preset class/command it registers before running — the command name changed across the laravel/ui 1.x → 2.x transition, and picking the wrong one silently does nothing useful.

Where to look first, in this order:

1. app/Http/Middleware/HandleInertiaRequests.php — the share() method is your global data channel.
2. resources/views/app.blade.php — the single root template with @inertia / @inertiaHead.
3. resources/js/app.js — the page resolver (typically require.context('./Pages', true, /\.vue$/)) and Inertia plugin registration.
4. resources/js/Pages/ — the starter page the preset drops in.
5. webpack.mix.js and package.json — confirm the preset wired .vue() and added the Inertia npm packages.

First real use case: open routes/web.php, replace the closure returning view('welcome') with return Inertia::render('Welcome');, point it at the generated page, and confirm the browser gets a full HTML response on first load and an X-Inertia JSON response on subsequent navigations. That round-trip is the whole mental model.

Implementation Patterns

Controllers return props, not views. The preset establishes the Inertia::render('Folder/Page', $props) contract. Keep controllers thin — query, map to arrays/Resources, return. Resist passing Eloquent models with lazy relations; only what's serialized is sent.

return Inertia::render('Users/Index', [
    'users' => UserResource::collection($users),
    'filters' => $request->only('search'),
]);

Global data goes in the middleware, page data in the controller. Auth user, flash messages, and app-wide config belong in HandleInertiaRequests::share() so every page gets them without repetition. Anything page-specific stays in the controller — over-stuffing share() is the most common cause of bloated payloads.

Page naming mirrors your route tree. Users/Index, Users/Show, Settings/Profile. This is the convention the resolver expects and the one that keeps require.context from needing exceptions.

Persistent layouts. Since the root Blade template holds <div id="app">, wrap pages in a layout component rather than putting nav/footer inside each page. In the Vue-era code the preset targets, that's layout: Layout on the component or a <layout> wrapper — either way, keep layout state (sidebar open, theme) out of page props so it survives navigation.

Forms use Inertia's form helper, not raw axios. this.$inertia.form({...}).post('/users') (or useForm if you've upgraded) gives you errors, processing, and recentlySuccessful for free, and it automatically surfaces Laravel's 422 validation bag into errors. Pair with @error-free Blade — all validation messaging moves into the page component.

Links must be Inertia links. <inertia-link href="/users"> (or <Link> post-upgrade). A plain <a> triggers a full document reload and defeats the entire setup; this is the easiest thing to get wrong in a code review.

Treat the preset as a fork point. Once the stubs are copied into your app they're yours — edit app.js, webpack.mix.js, and the middleware freely. If you need recurring scaffolding, copy the stubs into your own stubs/ directory rather than re-running the preset on every project.

Integration with auth. If the preset supports an --auth flag, use it; otherwise run php artisan ui:auth first, then the preset, and reconcile the route files by hand. Auth views rendered through Inertia is the one place you may deliberately keep Blade pages for a while — logging in via a full page load is often acceptable and avoids porting six forms on day one.

Testing. Use Inertia::assertInertia-style assertions (or assertInertia from inertia-laravel's testing macros, which may need adding separately) to assert on component name and prop shape instead of parsing HTML. That's the practical payoff of the pattern: GET /users is testable as data, not markup.

Gotchas and Tips

0.4.0 is a version-bump, not a revival. The release adds Laravel 7 support and nothing else — no new flags, no stub refresh, no frontend dependency updates. The Vue/Inertia JS stubs are still the same 2020-era code, and the Inertia ecosystem has moved twice since. The stubs will install @inertiajs/inertia and @inertiajs/inertia-vue at v0.x, register <inertia-link>, and use this.$inertia. Modern Inertia (v1/v2) uses @inertiajs/vue3 / @inertiajs/react, <Link>, and useForm. Plan a manual upgrade of app.js, package.json, and every component tag immediately after scaffolding. The PHP side (Inertia::render, HandleInertiaRequests, @inertia) survived the transition largely intact, so the backend scaffold is the durable half.

Don't read "Laravel 7 support" as "Laravel 8+ works." It doesn't. Frontend presets were a laravel/ui 1.x thing; laravel/ui 2.x replaced preset with ui/auth, and Laravel 8+ superseded the whole mechanism with Breeze and Jetstream. If php artisan preset isn't in php artisan list, the package's era doesn't match your app — stop and use Inertia's official starter kit or Breeze's Inertia stack instead of fighting it.

Presets overwrite files without asking. resources/js/app.js, resources/views/welcome.blade.php, webpack.mix.js, routes/web.php, and app/Http/Kernel.php may all be rewritten. Run it on a fresh app or a clean branch, and diff before committing. Never run it on an app with existing frontend work.

Middleware registration is easy to miss. The preset adds HandleInertiaRequests to the web middleware group in Kernel.php. If share() data silently never arrives, or you get a plain JSON response where HTML was expected, that registration is the first thing to check.

Node toolchain rot. Stubs from this era pin node-sass, old vue-loader, and laravel-mix v4/v5. On modern Node these fail to install or compile. Expect to bump laravel-mix and swap node-sass for sass before npm run dev succeeds on anything current. The 0.4.0 release did not touch package.json stubs, so this is still on you.

Asset versioning causes phantom 409s. Inertia sends X-Inertia-Version; when the compiled manifest hash changes (i.e., you rebuilt assets), Inertia forces a full reload. In dev this looks like "my page randomly reloaded" — it's correct behavior, not a bug. If it happens on every request, your middleware isn't receiving the version correctly.

Debugging the request type. In the network tab, a first visit is HTML; every Inertia navigation is a JSON response with X-Inertia: true. If you see full HTML on a click, the link isn't an Inertia link. If you see a JSON blob rendered as a page, the middleware isn't active. Those two checks resolve most issues.

Shared data must serialize. Closures, models with heavy relations, and anything holding a resource will inflate every response. Keep share() to scalars and small arrays.

No SSR, no devtools. This preset predates both. Server-side rendering requires separate setup (@inertiajs/server, a Node process, and a ssr entry point), and the Vue/React devtools extensions aren't wired in. Budget for those if they matter.

Extension points are the stubs themselves. There's no vendor:publish story worth relying on — the preset copies from its own src/Console/stubs (or equivalent). To customize recurring output, fork the package or copy the stubs into your own internal preset; don't expect config files to change the generated result.

Bottom line: 0.4.0 confirms the package is maintained only enough to track Laravel's major version, not to keep pace with Inertia itself — a one-line changelog eight months after the last release is the whole story. Use it as a one-time reference for how an Inertia + Laravel wiring is assembled (middleware, root Blade, resolver, Mix config), then either upgrade it aggressively or — more realistically in 2024+ — skip it and start from the official Inertia starter kit. The 2020-era stubs and near-zero install base are the signal: this is archaeology, not infrastructure.