Starter Kit Laravue Laravel Package

Getting Started

starter-kit-laravue is a scaffold, not a runtime dependency. You consume it once, then own the code.

composer create-project yanpenalva/starter-kit-laravue my-app
# or, if it is template-only:
git clone <repo> my-app && cd my-app && composer install

Then the standard Laravel bootstrap:

cp .env.example .env
php artisan key:generate
php artisan migrate --seed
npm install && npm run dev     # or: npm run build
php artisan serve

Look here first, in this order:

1. composer.json + package.json — confirms the Laravel major (10/11/12) and the Vue/Vite/Inertia versions you are actually inheriting.
2. routes/web.php — tells you whether this is a classic Blade+Vue hybrid or an Inertia SPA. This single file dictates everything else.
3. resources/js/app.js — the Vue mount point, plugin registration, and (if Inertia) createInertiaApp resolver that maps page names to components.
4. resources/js/Layouts/ and resources/js/Pages/ — the convention you must follow for new screens to render.

First use case: open the existing auth pages (login/register), copy one Page component and its controller method, and rename it into a placeholder CRUD screen. That gets you a working route → controller → props → Vue page loop in under ten minutes and validates your whole toolchain (Vite HMR, Ziggy/route helper, CSRF) before you write real code.

Implementation Patterns

Adding a page (the core daily loop). Route in routes/web.php → controller returning either view() (hybrid) or Inertia::render() (SPA) → component in resources/js/Pages/. Keep the component name identical to the string passed to Inertia::render(); the resolver is case-sensitive and a mismatch yields a blank screen with only a console warning.

Keep controllers thin, push shape into props. The starter kit's value is the wiring, not the domain logic. Return plain arrays/DTOs from controllers and let Vue own presentation. Avoid ->with() view-data helpers if you're on Inertia — props are the contract.

Reuse the shared layout instead of re-declaring nav/auth state every page. If the kit ships a Layout with v-if="auth.user", pass auth once via a middleware or HandleInertiaRequests::share(), not per-controller.

Form submissions. Use the kit's existing form helper (Inertia useForm, or axios + CSRF meta tag in the Blade shell). Pick one and delete the other — mixed patterns are the most common source of "why is my 419 coming back" in these kits.

Authorization. Laravel Policies still work normally; just remember the UI check (can props) and the server check are separate. Pass can: { update: ... } from the controller rather than re-deriving permissions in JS.

Scaffolding more than once. If you're starting several projects, fork the template repo and keep a main branch as your baseline. That way the upstream dependency bumps in releases like v2.0.0 are something you can cherry-pick rather than something you hope propagates.

Deployment. npm run build must run before php artisan config:cache in your pipeline, and the build artifact (public/build/manifest.json) must exist on the server — a missing manifest is a hard 500 on every page, not a silent fallback.

Gotchas and Tips

v2.0.0 is a dependency-only release — and it does not reach you. Every entry is a chore(deps) Dependabot PR (js-yaml, lodash, picomatch, brace-expansion, flatted, fast-uri, defu, serialize-javascript/terser-webpack-plugin). There are no source changes, no new features, no deprecations, and no documented breaking change. The major version bump is a hygiene signal, almost certainly driven by the serialize-javascript/terser-webpack-plugin group or a transitive range change.

The practical consequence: because this is a scaffold, existing projects get none of these patches automatically. composer update will not touch your package.json, and your package-lock.json is your own. If you generated a project from v1.0.3 or earlier, run npm audit in your own repo and bump those transitives yourself; that is the entire content of this release.

Treat the major bump as a lockfile event, not a code event. Before upgrading an existing app, diff package-lock.json between tags and confirm the Node engine requirement hasn't moved. fast-uri, picomatch, and brace-expansion are glob/matching utilities pulled in at build time — a version-range shift there can change which files Vite includes, so do a clean rm -rf node_modules package-lock.json && npm install and rebuild, rather than an incremental npm update. Use npm ci in CI to guarantee you're testing the committed lockfile.

Starter kits are not upgradable dependencies. The single biggest trap: expecting v2.0.0 fixes to land in a project you scaffolded from v1.0.3. Decide early whether you are maintaining a fork (keep the template repo, rebase your app on it) or a detached copy (accept that upstream releases are informational only). Most teams want the latter — say so explicitly in the README so nobody wastes a sprint trying to merge.

Blank page / white screen after adding a route. In order of likelihood: (1) Inertia::render() page name doesn't match the file path, (2) @vite directive missing from the Blade shell after you edited it, (3) stale public/build — run npm run build or restart npm run dev, (4) Vue resolve alias broken in vite.config.js.

Stale config after edits. php artisan config:cache / route:cache in local dev will silently keep old values. php artisan optimize:clear is the reflex to build.

Extension points worth knowing. The kit's own conventions — layout resolution, shared props middleware, Ziggy route registration — are the seams to customize. Override those rather than forking individual pages; it keeps your divergence from the scaffold small and auditable.

Where to spend review time. Not on the dependency PRs in this release. Spend it on the auth middleware, the HandleInertiaRequests share payload (a careless share() leaks data to every page), and your .env.example — those are the parts of a starter kit that quietly become production decisions.