Board Starter Kit Laravel Package

Getting Started

v1.0 is the first tagged release and ships with no changelog detail beyond a compare link, so treat it as an unversioned snapshot of main rather than a curated release. Verify the stack before you build against it:

git clone https://github.com/Hasnayeen/board-starter-kit
cd board-starter-kit && composer install && npm install
cp .env.example .env && php artisan key:generate
php artisan migrate --seed && npm run dev

Read these four things first, in order:

1. composer.json — tells you whether this is TALL/Livewire, Filament, or plain Blade + controllers. Everything downstream depends on this.
2. routes/web.php — the actual surface area of the app; starter kits hide their structure here.
3. app/Providers/*ServiceProvider.php and config/ — what is registered, what is publishable, what is opinionated.
4. database/migrations/ and database/seeders/ — the domain model and the demo data you can log in with.

First use case: boot it, log in with the seeded user, and walk the primary board flow end to end. A starter kit is only worth adopting if the happy path it ships matches the product you are about to build — confirm that in ten minutes before writing a line of code.

Implementation Patterns

Decide the adoption mode up front. There are only two sane ways to use a starter kit, and they diverge immediately:

• Fork and own it — delete .git, rewrite README, and treat every file as yours. Correct when the starter's domain matches your product (you are actually building a board app).
• Harvest and discard — cherry-pick the auth setup, layout components, and test scaffolding into an existing laravel new project. Correct when you only want the plumbing.

Do not attempt a hybrid; you will end up maintaining a merge conflict against an upstream that has no changelog.

Work at the feature seam, not the file level. When customising, prefer adding new Livewire components/controllers/policies alongside the shipped ones and swapping the route, rather than editing vendor-adjacent scaffolding in place. It keeps your diff against upstream legible when v1.1 lands.

Extract the domain early. Starter kits model a demo version of the domain (a single board, a single owner, no tenancy). Real requirements — teams, permissions, archiving, ordering — will fight the shipped schema. Do the migration rewrite in week one, not month three.

Testing pattern that pays off: the kit likely ships Feature tests for its happy paths. Keep them, and add a smoke test that asserts every route in routes/web.php returns a non-500 for an authenticated user. That single test catches most of the damage from your first round of refactors.

Seeders as fixtures. Point your local and CI environments at the same seeder so demo data, screenshots, and bug reports stay reproducible. Add a --class= variant for a minimal admin-only seed used in tests.

Gotchas and Tips

• No changelog = no upgrade path. Before you build on it, pin the dependency by commit SHA in your fork's README and record the date. When v1.1 arrives you will have nothing to diff against except the compare link.
• v1.0 with an empty changelog usually means a tag placed on main for distribution, not a stabilised API. Assume internal class names, component names, and config keys are all fair game to change.
• Node and PHP version drift is the most common first-run failure in starter kits. Check composer.json require.php and package.json engines before installing; mismatches surface as opaque Vite or autoload errors.
• .env.example is often stale. If seeding fails or login does not work, read the seeder and the auth config directly rather than trusting the example file.
• Asset pipeline traps: if npm run dev works but npm run build does not, the cause is nearly always an unpublished config or a missing entry in vite.config.js — not your code.
• Debugging a blank page: php artisan about, then storage/logs/laravel.log, then php artisan route:list. A starter kit that renders nothing is almost always a missing migration or an unregistered service provider, and those two commands will tell you which.
• Extension points to prefer: service providers over vendor edits, published config over hardcoded values, and Laravel's authorization policies over in-component role checks. These are the places where upstream changes will hurt you least.
• Before adopting, run php artisan test on a clean clone. If the shipped suite is red, the tag was not release-tested and you should budget for repair work.