Laravel Laravel Package

Getting Started

First: calibrate what this package is

intentui/laravel (published for a long time as justd/laravel — confirm the current Packagist name before scripting anything) is a Laravel 12 skeleton application, not a library you composer require into an existing project. Zero dependents confirms this — nothing consumes it as a dependency; you consume it by becoming it. Everything below assumes the day-to-day workflow is "scaffold once, then own the codebase."

composer create-project intentui/laravel my-app   # or: git clone … && composer install
cd my-app
cp .env.example .env && php artisan key:generate
npm install
php artisan migrate --seed
composer run dev        # serves app + vite + queue listener concurrently

As of v2.0.5 the frontend toolchain is Vite+, not plain Vite + Biome. So when npm run dev / npm run build aren't the scripts wired into composer.json, use the Vite+ binary directly (vp dev, vp build — run vp --help in the project root to confirm the surface). If composer run dev isn't defined at all, fall back to two terminals: php artisan serve and vp dev.

Where to look first (in order)

First use case: one resource, end-to-end

The fastest way to learn this skeleton is a single CRUD vertical slice, because it touches every layer the starter kit commits to:

php artisan make:model Post -mf --no-interaction
php artisan make:controller PostController --resource --no-interaction
php artisan make:request StorePostRequest --no-interaction
php artisan make:test PostTest --no-interaction

Then: define the migration → add a casts() method → write the Form Request → register a named route → render an Inertia page in resources/js/pages/posts/Index.tsx using Intent UI v4 primitives → link to it with Wayfinder instead of a string → assert it with Pest. That single loop teaches you 90% of the skeleton's opinions.

Implementation Patterns

Server side: the enforced Laravel way

These aren't suggestions in this repo, they're conventions the agent guidelines encode:

• Validation lives in Form Requests. Never inline $request->validate() in a controller. Include messages() alongside rules().
• Eloquent over DB::. Relationships with return types, eager-load to avoid N+1. Model::query() is the floor, not the ceiling.
• config() in app code, env() only in config/*.php. This is the single most common review comment.
• Named routes + route() for every internal link.
• APIs: Eloquent API Resources plus URI versioning, unless existing routes say otherwise.
• Slow work: ShouldQueue jobs, not inline loops in controllers.

final class StorePostRequest extends FormRequest
{
    /** @return array<string, array<int, string>> */
    public function rules(): array
    {
        return [
            'title' => ['required', 'string', 'max:255'],
            'body' => ['required', 'string'],
        ];
    }
}

Client side: Wayfinder is the seam

Every backend URL in React should come from a generated function, not a template literal. This is what wayfinder-development activates for:

import StorePost from '@/actions/App/Http/Controllers/PostController';
import { index } from '@/routes/posts';

// POST with typed payload
StorePost.post({ data: { title, body } });

// route-model binding: {post:slug} → pass the key name
show({ slug: post.slug });

// merge with current query string; null deletes a key
index({ mergeQuery: { page: 2, sort: null } });

Because these are derived from routes/web.php, the practical workflow is: change a route → let the dev server regenerate → fix the TypeScript errors it surfaces. The compiler becomes your route-change regression test. After the Vite+ switch, regeneration still happens on dev-server start — but verify it once on an existing checkout, since the plugin now runs inside a different build pipeline.

Intent UI v4: vendored components, not an import

Intent UI components live in your repo; you compose and edit them. The v4 migration in v2.0.5 touched that vendored layer, so the working rules are:

• Read the component source before using it. Treat resources/js/components/ui/* as your own code, because it is. There is no node_modules version to pin against.
• Prefer composition over prop soup. Wrap primitives in page-local components (resources/js/components/posts/…) so the next Intent UI bump touches fewer files.
• When upstream ships a new component version, port the diff into your copy — don't overwrite blind, or you'll lose local theming in @theme.
• Check variants and slot names after an upgrade. v3→v4 changes component APIs; silently-dropped props render as a plain unstyled element rather than throwing, which is the hardest kind of bug to spot in review.

Frontend tooling: Vite+ replaces Biome

v2.0.5 removed Biome entirely. Day-to-day consequences:

vp dev      # dev server + HMR (replaces `npm run dev`)
vp build    # production build (replaces `npm run build`)
vp check    # lint + format check — use this in CI
vp fmt      # format in place

• Delete stale assumptions: no biome.json, no npm run lint / npm run format scripts unless package.json redefines them. Rewrite CI steps to call vp check.
• Editor setup: uninstall/disable the Biome extension for this workspace so it doesn't fight the new formatter. Format-on-save against two formatters produces noisy diffs that hide real changes.
• Formatting churn is expected once. The first vp fmt across a pre-existing codebase will rewrite a lot. Land it as an isolated "chore: adopt Vite+" commit before any feature work, or every PR will be unreviewable.

Inertia v2 patterns worth adopting deliberately

• Deferred props for anything slower than ~200 ms, paired with a pulsing skeleton in the page component. A deferred prop with no empty state is a broken UX, and the guidelines call this out.
• WhenVisible + merging props for infinite scroll instead of a client-side pagination library.
• Polling for dashboards rather than websockets until you actually need them.
• Prefetching on hover for list → detail navigation.

Testing: Pest 3, feature-first

php artisan test --compact --filter=PostTest

• Default to feature tests; reach for --unit only for pure logic.
• Always use factories and check for existing states (->published()) before hand-rolling model setup.
• Obey the enforcement rule: every change ships with a test. The repo states this explicitly; treat a PR without a test as incomplete.
• Architecture tests are cheap here and prevent DB:: and env() from creeping back in.

Working with the agent tooling

The Boost MCP server is wired in for a reason — use it before guessing:

1. search-docs with broad, package-agnostic queries (['rate limiting', 'routing rate limiting']). Package + version are auto-injected; adding "Inertia" to the query hurts recall.
2. database-schema before writing a migration; database-query for read-only inspection; tinker for actual execution.
3. list-artisan-commands to confirm flags instead of reciting stale ones.

Be aware the model's priors are stale for anything touched by v2.0.5: it will suggest Biome commands and v3 Intent UI props. Correct it explicitly in prompts ("we use Vite+, not Biome").

Gotchas and Tips

There is no upgrade path for the skeleton — only for the framework. laravel/framework and the rest are ordinary Composer dependencies, so composer update still delivers patches. But bootstrap/app.php, the Vite+ config, the page structure, the vendored Intent UI components, and the Wayfinder wiring are now yours. v2.0.5 will not merge into your app. You get Intent UI v4 and Vite+ only by manually porting them. Budget a half-day for the tooling half and longer for the component diff, and don't expect the "last release" date to mean anything for your maintenance.

Migrating an existing app to v2.0.5 — suggested order. (1) Land vp fmt as a standalone commit. (2) Replace Biome: drop biome.json, remove the extension, repoint CI at vp check. (3) Port Intent UI v4 components one directory at a time, running vp dev between each to catch variant/slot breakage. (4) Only then touch feature code. Doing 3 and 4 together makes regressions impossible to attribute.

Never hand-edit resources/js/actions or resources/js/routes. They're build artifacts. Symptoms of fighting this: imports that resolve in the editor but 404 after a production build, or route helpers that vanish on the next dev-server restart. If a Wayfinder import is missing, the cause is almost always a route that isn't named, or a dev process that hasn't restarted — and after the Vite+ switch, double-check the Wayfinder plugin is still registered in the new config file before you debug anything else.

Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest means the asset pipeline, not your PHP. Run vp build (or vp dev / composer run dev). When a user reports "my change isn't showing," ask about the dev server before debugging React.

Laravel 12 structure traps. Middleware registered in a nonexistent Kernel.php will silently do nothing. Console commands go in app/Console/Commands/ and are auto-discovered — no registration step. Providers go in bootstrap/providers.php.

Modifying a column drops everything you omit. In Laravel 12 migrations, ->change() requires restating nullable, default, comment, and index attributes. Rewrite the full definition every time.

Prefer casts() over $casts. Match whichever the sibling models use, but new models should use the method.

Tailwind v4 changes the mental model. No tailwind.config.js by default. Theme tokens go in @theme inside app.css. Most blog posts and LLM output you'll find is v3 — sanity-check any theme.extend snippet before pasting it. Same caution applies to Intent UI: v4 examples are scarce, so read the vendored source as the source of truth.

Sanctum v4 auth: pick one model and stay there. Cookie-based SPA auth for first-party Inertia pages; token abilities only for genuinely external clients. Mixing the two in one app produces intermittent 401s that are painful to trace.

Pest 3 and PHPUnit 11 coexist. A test in the wrong directory or with a mismatched suffix simply won't be collected. If --filter finds nothing, check phpunit.xml test suites before rewriting the test.

Don't create documentation files. The guidelines forbid it unless explicitly requested — put knowledge in tests and PHPDoc instead.

Extension points, in order of leverage: Form Requests (validation policy), policies/gates (authorization), Inertia shared data via middleware (global props), queued jobs (anything over a second), the Wayfinder-generated layer (the typed contract between Laravel and React), and your vendored Intent UI component wrappers (the visual contract). Everything else in the skeleton is scaffolding you're free to replace.