Laravel Quickstart Dashboard Inertia Laravel Package

Getting Started

This package is a scaffolding/quickstart kit: it wires Laravel + Inertia into a working authenticated dashboard rather than providing runtime services. Treat it as a one-shot generator, not a long-lived dependency you call from your app code.

1. Read the repo before installing. Start with the README and composer.json (Laravel + Inertia + frontend stack versions), then the src/ service provider and any stubs/ or resources/ directory — that's where the actual value lives. The tests/Browser directory also tells you Pest 4 browser testing is part of the intended workflow.
2. Install into a fresh app, not an existing production codebase:

   composer require webmintydotcom/laravel-quickstart-dashboard-inertia --dev
   php artisan vendor:publish --tag=quickstart-dashboard
   

   Check the exact publish tags/commands in the provider — quickstart packages usually ship several tags (config, stubs, frontend assets) and publishing only one will leave you with a half-wired app.
3. Run the install command if one exists (typically php artisan quickstart:install or similar). Verify routes/web.php, app/Http/Middleware/HandleInertiaRequests.php, and resources/js/app.{ts,js} were patched — these are the three places scaffolding silently fails.
4. First use case: get /dashboard rendering behind auth middleware with one seeded user, then delete/replace the demo pages. That end-to-end path validates Inertia's root blade template, Vite config, and the middleware share payload in one go.

Note: pin the version explicitly and diff the generated files against your app after each upgrade. The 1.1.1 release is a .gitignore fix only — it gives no signal about API stability.

Implementation Patterns

Scaffold once, then own the code. The dominant pattern with quickstart packages is vendor:publish then commit the output. After the first publish, the package becomes a reference implementation — copy its patterns rather than re-publishing on each upgrade, which would clobber your edits.

Layer your own pages on the generated layout. Keep the package's layout component (usually resources/js/Layouts/AuthenticatedLayout) as the shell and add new pages as siblings of the generated ones. Register routes in your own routes/web.php group so a future re-publish doesn't collide with your controller names.

Reuse the Inertia share contract. HandleInertiaRequests::share() is the seam between backend and every page component. Add auth user, flash messages, and app-level config there instead of threading props through each controller — this is the package's main opinion and it's worth keeping.

Form pattern: generated pages typically post to a resource controller and return redirect()->route(...)->with('status', ...). Match that convention exactly so the shared flash prop renders without extra plumbing; deviating means custom toast wiring on every page.

Integration tips

• Install with --dev if the package is purely generative — you don't want it in production composer install.
• If you use Pest browser tests, keep the package's tests/Browser structure; 1.1.1's .gitignore change assumes screenshots land in tests/Browser/Screenshots, which is Pest's default failure output path.
• Wire Vite before running the frontend: quickstart kits assume a specific vite.config.js input list (resources/js/app.ts, resources/css/app.css). Mismatched inputs are the #1 cause of a blank Inertia page.
• If you're on React instead of Vue (or vice versa), check which stub set the package ships — publishing the wrong variant is not reversible without a clean tree.

Gotchas and Tips

Screenshot noise in git (addressed in 1.1.1). Failure screenshots are generated by Pest browser tests and are non-deterministic binary files; committing them bloats history and creates merge conflicts. The 1.1.1 fix ignores tests/Browser/Screenshots. If you scaffolded on 1.1.0 or earlier, add the entry manually to your .gitignore — it is not retroactively applied. Also check whether you already committed screenshots (git rm -r --cached tests/Browser/Screenshots), because an updated .gitignore won't untrack existing files.

Publishing overwrites silently. Most quickstart packages use vendor:publish --force semantics that clobber modified files without confirmation. Before any re-publish, commit your work, then git diff the result. Better: git stash first and review the diff before applying.

Middleware and route ordering. Inertia requests must not fall through to web routes that return Blade views; if the dashboard renders raw JSON or a plain HTML page, check whether HandleInertiaRequests is registered in the web group and whether your route actually returns Inertia::render.

npm run dev vs build. Scaffolding kits frequently ship a vite.config.js with a dev server host that won't match Docker/Valet/Herd setups. Blank page + console 404 on /build/assets/app-*.js means you ran dev but the blade is using @vite without the hot file, or vice versa.

Debugging checklist for a broken page:

1. php artisan route:list — is the route hitting the expected controller?
2. Inertia devtools / the page prop in the HTML source — did the component name resolve?
3. resources/js/Pages/... path casing — case-sensitive on Linux CI, works locally on macOS.
4. storage/logs/laravel.log for Inertia\Response exceptions from missing props.

Extension points worth knowing: the service provider (for adding your own share data or macros), the layout component (for nav/branding), and HandleInertiaRequests (for global props). Everything else is generated app code — treat it as yours and modify freely.

Upgrade policy. With only a .gitignore patch in 1.1.1, there's no functional change since 1.1.0. Stay on the latest patch, but diff between minor versions before bumping — a quickstart package's minor release can restructure stubs, which is effectively a breaking change for anyone re-publishing.