Laravel Quickstart Inertia Laravel Package

Getting Started

webmintydotcom/laravel-quickstart-inertia is a project scaffold rather than a runtime dependency — you consume it once, at create-project time, and then live inside the codebase it generates. Treat 2.2.1 as the baseline version to start new work from.

composer create-project webmintydotcom/laravel-quickstart-inertia my-app
cd my-app
composer install
npm install
npx playwright install chromium   # required as of 2.2.1
php artisan migrate
npm run dev

The npx playwright install chromium step is not optional and is not covered by npm install. On 2.2.0 and earlier a fresh clone would throw PlaywrightNotInstalledException the first time you ran a Pest browser test. 2.2.1 adds playwright to devDependencies, which fixes the Node package resolution, but the browser binary still has to be downloaded separately. Do both, in that order.

Where to look first, in this order:

1. README.md — the browser-testing section was corrected in 2.2.1 and is now accurate; trust it over older blog posts.
2. tests/Browser/ — the Pest browser test suite and the conventions the generated tests follow. Read one passing test end to end before writing your own.
3. .ai/ or the agents directory (wherever pest-browser-writer and pest-browser-runner are registered) — these are the two agents the release notes reference, and they define the intended test-authoring loop.
4. routes/ and resources/js/Pages/ — standard Inertia page/route pairing; this is where your first feature lands.

First use case worth doing on day one: scaffold the app, run the existing browser suite green (./vendor/bin/pest tests/Browser), then use pest-browser-writer to generate a test for one page you actually care about and pest-browser-runner to iterate on it. That validates the whole toolchain — Node, Playwright, Chromium, Pest, and the app's dev server — before you've written any product code.

Implementation Patterns

Scaffold, then diverge deliberately. This is a starter kit, so the generated code is yours and upgrades are not automatic. Don't try to composer update the quickstart package itself in a live app; instead, diff a fresh scaffold against your project when a new minor lands and cherry-pick conventions (config, test setup, agent definitions) you want.

Page-per-route Inertia flow. The everyday loop is: controller returns Inertia::render('PageName', $props) → page component in resources/js/Pages/ → typed props. Keep the prop contract explicit (TypeScript interfaces or a shared types file) so the browser tests and the frontend agree on shape.

Agent-driven test authoring. The two agents map cleanly onto a workflow:

• pest-browser-writer — describe the user journey in natural language, let it draft the Pest browser test under tests/Browser/.
• pest-browser-runner — run and iterate on that test, including reading failure screenshots to self-correct.

Use them in sequence, and always review the generated assertions. Agents are good at producing a runnable test and mediocre at producing the right assertions — the value is in the scaffolding and the run/debug loop, not in trusting the semantics.

Browser tests as the integration layer. With Inertia there's no meaningful server-rendered HTML to assert against, so Feature tests get thin fast. The practical split: Feature tests for validation, authorization, and redirects; Pest browser tests for anything that crosses the JS boundary — form submission, modal state, navigation without full reload. Reserve the browser suite for those and it stays fast enough to run on every push.

CI wiring. Two stages that must not be collapsed:

- run: npm ci
- run: npx playwright install --with-deps chromium
- run: ./vendor/bin/pest --testsuite=Browser

--with-deps matters on Linux runners; the package's README documents the local npx playwright install chromium form, but CI images usually need the system libraries too.

Screenshots as debugging artifacts. tests/Browser/Screenshots is now git-ignored (2.2.1), which confirms the intended workflow: on failure, open the screenshot locally to see what the browser saw rather than re-running with more logging. Pair this with the runner agent, which consumes those same artifacts.

Gotchas and Tips

• PlaywrightNotInstalledException has two causes. 2.2.1 fixes the missing playwright devDependency, so npm install now resolves the Node module. It does not download the Chromium binary. If you still see the exception after upgrading, you skipped npx playwright install chromium.
• Upgrading an existing scaffold won't pick up the fix. Because this is a starter kit, devDependencies in your project came from the version you scaffolded with. If you created the app on 2.2.0, add playwright to devDependencies yourself and commit the lockfile change — the release note is only automatically true for new projects.
• Screenshot churn. If you scaffolded before 2.2.1, add tests/Browser/Screenshots to .gitignore manually. Failure screenshots regenerating on every local test run make for noisy diffs and accidental commits of UI state.
• Stale README in memory. Earlier versions' instructions omitted the Playwright browser install. If you have a setup script, Dockerfile, or onboarding doc copied from a pre-2.2.1 README, update it — otherwise every new team member hits the same exception on their first browser test.
• Dev server dependency. Browser tests need the app reachable. Prefer Pest's built-in server handling over manually backgrounding php artisan serve in CI; a manually started server that dies mid-run produces confusing timeouts that look like assertion failures.
• Screenshots are not assertions. They're ignored and ephemeral — don't build workflows that depend on their presence (e.g. artifact-upload steps that assume a file exists). Treat them as best-effort debugging aids and make CI tolerate their absence on passing runs.
• Patch-level release, low risk. 2.2.1 contains no breaking changes: a devDependency addition, a .gitignore entry, and documentation corrections. There is no migration to perform; re-scaffold if you want the fixes for free, or hand-apply the three changes to an existing project.
• Extension point to watch. The pest-browser-writer / pest-browser-runner agents are the most opinionated and least stable surface in the package. If you customize their prompts or add project-specific browser-test conventions, record those locally so a future scaffold diff is easy to reconcile.