Koamistarterkit Laravel Package

Getting Started

KoamiStarterKit is a Laravel starter kit (not a typical drop-in library), so "installing" it means scaffolding a new application rather than composer require-ing into an existing one.

Start with the create-project flow from the release notes:

composer create-project koamishin/KoamiStarterKit my-project
cd my-project
composer run dev

composer run dev is the intended entry point — it wraps the usual dev stack (Vite, queue listener, and the PHP server) into one process, so you should not need to juggle npm run dev and php artisan serve in separate terminals.

Where to look first:

1. Auth and roles. v1.4.0-beta.3 fixes role seeding (fix: seed default roles and create missing user role on signup), so roles are a first-class concept. Run php artisan migrate --seed before touching anything else, then inspect the roles/permissions seeders and the registration flow to understand what a new user is granted by default.
2. Layouts. The prevent double layout shell on dashboard and settings fix signals a layout/shell component arrangement worth reading before adding pages — new views should follow whatever pattern the fixed pages now use.
3. Docker. Both ghcr.io/koamishin/KoamiStarterKit:1.4.0-beta.3 and the rolling dev-latest alias are published. Pull the pinned tag for anything resembling a real environment; dev-latest moves under you.

First use case: stand up a project, sign up a user, confirm the new account receives its role, and land on the dashboard without a duplicated shell. That single walkthrough exercises every fix in this release and is the fastest way to validate your install.

Implementation Patterns

Treat it as a fork, not a dependency. Because this is a starter kit, upstream changes are not delivered by composer update. Track the repository and diff releases against your project manually, or you will silently miss fixes like the double-shell and role-seeding corrections in this beta.

Pin the beta deliberately. You are on 1.4.0-beta.3. Pin the exact tag in your Dockerfile or compose file; do not rely on dev-latest outside throwaway previews. If you need stability, decide up front whether to track the 1.3.x line or ride the 1.4 betas, and document that choice for the team.

Roles at signup. With the signup-time role creation fixed, the natural pattern is to hook business logic onto the registration event rather than re-deriving a user's role in each controller. Extend the existing role assignment path instead of asserting roles ad hoc, or you will get divergence between seeded users, invited users, and self-registered users.

Layout composition. Since the shell duplication was just repaired, avoid wrapping dashboard-style pages in an additional shell component of your own. Follow the existing page structure and let the layout layer own the chrome; nesting will reintroduce exactly the bug that was fixed.

Vite config. The exclude tool configs from Vite-Plus format scope fix implies Vite-Plus formatting runs over config files and was previously catching tooling configs it should not rewrite. If you add new tool configs (linters, formatters, CI helpers), check whether they need to be excluded too — and if you maintain your own Vite-Plus setup, mirror that exclusion list.

Docker-based integration. For CI or team onboarding, the published image is the shortest path to parity. Build your app on top of the image rather than reconstructing the PHP/Node toolchain, and keep the image tag and your composer lock in sync when you bump versions.

Gotchas and Tips

Beta means beta. A 1.4.0-beta.3 release is pre-stable. Do not assume APIs, config keys, or the generated file structure are frozen; re-read diffs on each beta bump. Chores like "update agent docs, skills, and project rules" land in the same stream, so changelogs will be noisy — filter for fix: and feat: entries when triaging.

Seed before debugging roles. The role fix only helps if seeders ran. If a freshly registered user has no role, check migration and seeding order first; a partially seeded database reproduces the old bug and can look like a regression.

Layout bugs often surface only on specific routes. The dashboard and settings fix was route-scoped. If you refactor layout composition, spot-check every top-level page — dashboard, settings, and any custom pages you added — not just the one you were editing.

Clear caches after pulling a new image or tag. Stale compiled views and cached config are the usual suspects when a fix appears not to have landed. php artisan optimize:clear before concluding the release is broken.

Vite-Plus scope errors. If formatting or build steps suddenly touch files you did not expect, verify your exclusion patterns. The upstream fix excludes tool configs; files you add later are not automatically covered.

Extension points to prefer. Favour the seeders, the registration/signup path, and the layout components over editing vendor or core scaffolding files. Those are precisely the areas the maintainers are actively patching, so customisation there will conflict on your next manual merge.

Watch the source, not just the changelog. Auto-generated release notes with commit hashes are terse. For anything that changes behaviour under you, read the linked commit — the one-line summary rarely conveys the blast radius.