Jetstream Inertia Generator Laravel Package

Getting Started

Prerequisites — check these before you install anything. The generator assumes a stock Laravel + Jetstream app running the Inertia stack (php artisan jetstream:install inertia) with Vite and Tailwind already building. If your vite.config.js, resources/js/app.js, tailwind.config.js, or resources/js/Pages tree has been hand-modified, stop and read the Gotchas section first — a retrofit here is a cherry-pick job, not an install.

Install as a dev dependency. It is a scaffolding tool that runs at development time; it has no business in your production manifest.

composer require savannabits/jetstream-inertia-generator --dev

Pin the version ("savannabits/jetstream-inertia-generator": "3.4.0" in composer.json, or at minimum let the lockfile hold it) so a routine composer update sweep doesn't silently move your generator out from under you. Record why it's pinned in the PR description.

Where to look first, in this order:

1. php artisan list — filter for jetstream-inertia (or whichever namespace the installed version registers). The command signature and option list are the actual documentation; the release notes don't publish one, and the signature is not guaranteed stable across minors.
2. php artisan vendor:publish — list the package's publishable groups, then publish the config and stubs into your app.
3. config/jetstream-inertia*.php — this is where field-type mappings, paths, and stub locations live. Read it end to end before generating anything; it tells you what the tool will write and where.
4. The published stubs/ directory — this is the real contract. Every generated PHP and Vue file is a rendering of one of these. Skim the index/create/edit Vue stubs and the controller stub so you know what you're about to commit.
5. routes/web.php — generation appends route registrations here. Note the current state before you run it; that's your diff baseline.

First use case: one trivial resource, end to end. Pick something with two or three scalar fields and no relationships — a Post with title (string), body (text), published (boolean) is ideal. Generate it, then immediately:

php artisan migrate
npm install && npm run dev

Open the index page, create a record, edit it, delete it. If a page renders unstyled, that is almost certainly your Tailwind content glob (see Gotchas), not the package. Commit immediately after generation — before any manual edits — so you have a reviewable diff and a rollback point. The commit is the deliverable of your first run.

Implementation Patterns

Generate, review, then customise — never the reverse. The single most important workflow rule: treat a generated module as a one-shot code drop that becomes your source the moment it's committed. Do not plan to re-run the generator over a module you've edited. If a schema changes materially, generate into a scratch branch, diff its output against your customised module, and port the deltas by hand.

The module loop, per resource:

1. Decide the schema — including foreign keys and enum-ish fields — before generating. Field types drive both the migration/validation and the form input widgets, so a wrong type means editing PHP and Vue in three places afterwards.
2. Run the generator on a feature branch.
3. git diff and read it. Look specifically at: the migration's column types and nullability, the form request's rules, the controller's route-model-binding and authorization, and the Vue form inputs.
4. php artisan migrate, npm run build, then smoke-test index/create/show/edit/delete plus one validation failure.
5. Add the route to your navigation menu — the generator writes the route and the page, but it does not know your sidebar.
6. Commit as generated; make house-style edits in a second commit. Two commits now saves you an archaeology session in six months.

Use existing models as the anchor where you can. Generating against a model you've already defined (or generating and then reconciling with your own model) keeps you from ending up with two sources of truth for $fillable, casts, and relationships. Anything the generator omits — relationships, accessors, scopes, policies — you add by hand; the generator does not infer your domain.

Authorisation is yours. The generated controller and routes get you to a working page; they do not know your permission model. Bolt on policies (php artisan make:policy) and either $this->authorize() calls in the controller or can: middleware on the route group. Do this as a standard step in the loop, not per-module, otherwise one resource will ship unprotected in the rush.

Codify house conventions in the stubs, not in a review checklist. If two or more people will generate modules, publish the stubs and edit them once: your layout component name, your page-title conventions, your useForm wrapper, your standard index columns, your Pagetables column definitions and action buttons. That is the compounding-returns play — it turns "generated code that mostly matches our style" into "generated code we merge without edits." Keep the stubs in version control and treat stub changes as reviewed platform changes, not personal tweaks.

Customise index tables in the Vue page, not in PHP. Pagetables configuration (which columns show, formatting, row actions) lives in the generated Pages/ component. It's ordinary Vue — edit it directly and accept that it's now yours.

Keep Jetstream feature flags and generator flags aligned. If your app was installed with teams or API tokens, make sure the generator's options reflect that; mismatched flags are the usual reason a generated app ends up half-wired, with orphaned pages or missing guards.

Gotchas and Tips

The Tailwind content glob is the #1 false alarm. If generated Vue pages render with no styling, check tailwind.config.js — it must include ./resources/js/**/*.vue (and your .js). Fix the glob, restart the dev server, don't file a bug.

Regeneration overwrites. There is no merge. Assume the tool prompts-or-clobbers and plan accordingly: generate on a clean branch, never run it twice into the same working tree without a commit. If you want to experiment, git stash or branch first. Confirm the actual behaviour (skip / prompt / overwrite) yourself on the first run — the docs don't promise idempotency.

Version skew is discovered by experiment, not by documentation. There is no published support matrix for PHP / Laravel / Jetstream / Inertia / Vite / Node. The v3.4.0 release bumped Inertia, Laravel Vite, and Laravel — which likely narrowed the supported range for older majors without saying so. Validate your exact combination on a disposable Jetstream spike app or branch: clean composer install, clean npm install, a production npm run build, and an SSR build if you use SSR. Write the working matrix down internally; it's the cheapest artefact you'll produce from the pilot.

npm peer conflicts are a signal, not noise. A peer-dependency conflict between the generated package.json expectations and your installed Inertia/Vite versions is the tool telling you the matrix is wrong. Don't --force past it; resolve the version alignment first.

Route and Ziggy caches. After generating, if links 404 or route() throws in Vue, run php artisan route:clear && php artisan route:list to confirm the routes registered, and regenerate Ziggy if you use it. Inertia page resolution failures are usually a case-mismatch between the controller's Inertia::render('Posts/Index') and the actual file path — check both on a case-sensitive filesystem (Linux/CI), where a page that worked on macOS will fail.

Form request rules are a starting point. Generated validation reflects field types, not your domain rules — unique constraints, exists on foreign keys, conditional required_if, file mime/size limits. Review the request class every time; this is the most likely place for a subtle bug to ship.

Migrations: check the timestamp ordering. If you generate several resources whose tables reference each other, the generator may not order the migration timestamps for you. Rename the files so foreign keys resolve on a fresh migrate, or you'll only find out in CI on a clean database.

Debugging checklist, in order: php artisan route:list → does the route exist and point at the generated controller? → resources/js/Pages/... → does the file the controller names actually exist, with matching case? → npm run build → any compile error in the generated Vue? → browser console → Inertia response shape. Only after all of that conclude the package is at fault; with zero dependents and a single maintainer, you are likely the first person to hit your specific combination.

Extension points worth knowing: published config (paths, type mappings), published stubs (the real lever for standardisation), and the generated files themselves — all plain Laravel and Vue you own outright. If you need to go deeper than stubs allow, subclass or bind your own generator rather than patching vendor/.

Set the policy in writing before a second developer uses it: pin the version, generate on a branch, commit before customising, never regenerate over customised files, upgrades are a regenerate-and-diff exercise. The tool is a productivity lever; the discipline around it is what keeps it from becoming a maintenance tax.