Laravel Starter Kit Laravel Package

Getting Started

This is a starter kit, not a runtime library — you consume it once to scaffold a project, then work in your app. Treat the README (recently corrected in v1.4.4) as the source of truth before anything else.

1. Read the README's CLI section first. v1.4.4 added explicit docs for installing and updating projects with the CLI — that's the intended entry point and supersedes the older manual composer create-project / clone-and-go flows.
2. Scaffold a project using the documented CLI command, then confirm .starter-kit.json exists at the project root. This file records the starter kit version the project was generated from and is what future update runs diff against.
3. Run the standard Laravel bootstrap (cp .env.example .env, php artisan key:generate, migrate, npm install && npm run dev) — the kit ships a pre-wired frontend stack (Vue + vue-sonner toasts, per the v1.4.4 stylesheet fix).
4. First real use case: stand up a new internal app or client project with auth, layouts, and toast/notification plumbing already done, then delete anything you don't need.

Implementation Patterns

CLI-driven lifecycle. The kit now has a defined loop: install via CLI → work → pull starter kit updates via CLI. Rather than re-cloning or copy-pasting, keep .starter-kit.json committed so update runs know the baseline version.

Version pinning as a contract. The new release workflow records the version into .starter-kit.json at publish time. That means: don't hand-edit it, and don't delete it — you'll break the updater's ability to compute what changed between your baseline and the latest release.

Template maintenance workflow. If you fork or extend the kit, the relevant CI pieces are worth copying:

• A release workflow that stamps .starter-kit.json on tag.
• Scoped permissions: contents: write on only the release job (v1.4.4 tightened this) — good default hygiene for any release pipeline you build.
• An exclusion mechanism so starter-kit-only files don't leak into generated projects (chore: exclude starter kit only files from new projects). If you maintain a fork, add your own tooling/config files to that exclusion list rather than relying on manual cleanup post-scaffold.

Frontend integration. The vue-sonner stylesheet import fix means toast styling works out of the box; when adding notification UX, use the shipped vue-sonner setup rather than introducing a second toast library. If you're layering on a design system, verify CSS import order — a single missing import 'vue-sonner/style.css' is exactly the class of bug v1.4.4 patched.

Downstream update pattern. Run the CLI updater on a branch, review the diff, and only then merge. Because the updater mutates application files, treat it like a dependency bump with a code review, not a one-liner.

Gotchas and Tips

Starter-kit-only files are excluded on purpose. Files present in the kit repo but absent from generated projects are intentional (CI configs, release scripts, kit tooling). Don't chase "missing" files after scaffolding — they were never meant to ship. Conversely, if you fork and add tooling, you must register it in the exclusion list or every generated project inherits it.

.starter-kit.json is state, not config. Deleting or hand-editing the version field is the most likely way to break updates. Commit it, don't gitignore it, don't rewrite it.

Update conflicts are the main day-to-day risk. The CLI updater writes into files you've almost certainly edited (routes, layouts, config). Always run it on a clean branch with no uncommitted work, and expect to resolve conflicts in exactly the files you've customised most.

Dependency bumps are routine here. Most of v1.4.4 is chore(deps) and chore: update noise (plus a setup-php bump in the Actions group). Don't infer API changes from these — they're maintenance, not behaviour. Conversely, if you pin your own forks, expect near-zero friction tracking the kit's non-CI changes.

Docs lagging is the historical failure mode. The very first item in v1.4.4 is a README correction, followed by a docs PR for the CLI install/update flow. If your team hit confusion on v1.4.1 or earlier, the answer is now in the README — check it before filing issues.

Extension points stay in your app. There's no package-level service provider or config file to hook into; customisation happens by editing the scaffolded code. That's freeing but means upgrades are diff-based, not override-based — the more you rewrite core files (auth, layouts), the more conflict resolution you'll own on every kit update.

Debugging tip: if something works in the kit repo but not in your generated project, diff against the exclusion list first. If something works locally but breaks in CI, check that the release workflow's scoped permissions still cover whatever new job you added.