Laravel Starter Kit Laravel Package

Getting Started

Consume it as a project, not a dependency. The kit is scaffolding; you create an application from it and then own the code. Do not composer require it into an existing app.

# Option A — create from the repo (if it ships a create-project-compatible tag)
composer create-project rockero-cz/laravel-starter-kit my-app 1.3.3

# Option B — clone and initialize
git clone https://github.com/rockero-cz/laravel-starter-kit my-app
cd my-app && composer install
cp .env.example .env && php artisan key:generate
php artisan migrate
npm install && npm run build
php artisan serve

Pin the tag explicitly and land the scaffold as one commit (chore: scaffold from starter kit 1.3.3). Every later change is then diffable against a known baseline — this is the single highest-value habit with a starter kit.

Read these files before writing any code, in order:

1. composer.json — Laravel/PHP constraints and the frontend stack. This determines whether the kit fits your platform baseline at all.
2. routes/web.php + any routes/auth.php — how the auth and admin surfaces are wired.
3. app/Http/Controllers/ — especially the auth controllers; note whether it's Breeze, Fortify, or hand-rolled. This dictates how you extend login/registration.
4. app/Providers/ — where modular wiring, view composers, and Blade component registrations live.
5. resources/views/layouts/ and resources/views/components/ — the admin layout contract (@extends vs <x-layout>) you'll build every screen against.
6. tests/ and .github/workflows/ — the testing and CI standard you're inheriting. If either is missing, add it in week one rather than month three.

First use case to validate end-to-end: log in with a seeded/migrated user, hit the admin dashboard, and add one trivial CRUD screen (list + form + validation + a feature test). Doing this on day one surfaces the layout contract, the routing conventions, and whether the test harness actually runs — all before you've written domain code.

Implementation Patterns

Extend the auth flow, don't replace it. The kit ships working auth; the cheapest path is additive. Add a profile field by following the existing chain rather than rewriting it:

• migration → $fillable on User → validation rules in the registration controller/action → form field in the registration view.
• For anything beyond that (2FA, social login, API tokens), check the underlying package first — if it's Breeze/Fortify, install its documented feature rather than hand-rolling inside the kit's copy.

Build against the layout, not around it. Every admin screen should be a thin child of the provided layout. Typical shape:

@extends('layouts.admin')  {{-- or <x-admin-layout> if the kit is component-based --}}

@section('title', 'Orders')

@section('content')
    <livewire:orders-table />  {{-- or a plain table partial --}}
@endsection

Add new navigation entries in one place (layout partial or a nav config) so a sidebar change never becomes a fifteen-file diff.

New domain code follows the modular convention exactly. Whatever the kit's structure is — app/Modules/*, domain folders, or plain Laravel app/ — put your feature in the same shape as the shipped ones. A new module typically needs: model + migration, controller(s), route file (registered from the module's service provider), views, and tests. Copy the structure of an existing shipped module as the template; it's faster and keeps you rebase-friendly.

Keep the diff to upstream small. The core discipline: when you override a kit default, prefer config or a subclass/publish over editing the shipped file. Concretely:

• Publish and edit config files rather than patching vendor defaults inline.
• Prefer adding a new Blade component over rewriting a shipped one.
• Extend shipped controllers/middleware rather than editing them in place, when the kit's design permits it.

This is what makes a future upstream release portable.

Daily test/quality loop should mirror whatever the kit ships (php artisan test, ./vendor/bin/pint, ./vendor/bin/phpstan). If the kit has no static analysis, add Pint + PHPStan at level 5 immediately — a fork with no guardrails decays fastest.

Track upstream deliberately, not passively. Keep a short UPSTREAM.md recording the pinned tag and, per release, one line: 1.3.3 — reviewed diff, ported session-cookie fix. Without provenance, the next rebase starts from archaeology.

Gotchas and Tips

It is a fork, not a dependency — there is no composer update path. Upstream bugfixes never arrive on their own. Budget a named owner and a few hours per upstream release for diff review. Unowned forks silently freeze on stale framework versions.

1.3.3 has an empty changelog body (compare link only). Treat it as low-risk by semver convention, not by evidence. Read the 1.3.2...1.3.3 diff before seeding new services from it — a defect in a template multiplies across every project you start.

Don't retrofit it into an existing app. Cherry-pick discrete files instead: CI workflow, Pint/PHPStan config, Docker/compose, base test helpers. Wholesale migration fights your existing auth stack and conventions and usually loses.

Auth stack swaps are expensive. If the kit uses Blade + session auth and you need an SPA/API token flow, decide that before writing domain code. Retrofitting Sanctum/Passport onto a fork-shaped app later touches routes, middleware, views, and tests simultaneously.

Cache staleness after scaffolding or edits. The usual Laravel traps bite harder on a fresh scaffold because you're editing views, routes, and config all at once:

php artisan optimize:clear   # config/route/view/cache
php artisan route:list       # confirm auth + admin routes actually registered
php artisan about            # driver/env sanity check in one shot

Review the baked-in infrastructure defaults before production, not after: SESSION_DRIVER, CACHE_STORE, QUEUE_CONNECTION, mail transport, and anything auth-related that assumes single-node. The kit's "sensible defaults" are optimized for local development; a multi-node deploy with database sessions and a sync queue will behave differently than the kit author tested.

.env.example drift. Starter kits frequently add a variable to .env but forget .env.example, or vice versa. Diff the two before onboarding a teammate — "works on my machine" here is almost always a missing key, not a code bug.

Frontend build coupling. If the kit ships Vite, npm run build is part of the deploy contract. Check the Node version in the kit's CI against your build image; a mismatched Node major is a common first-deploy failure.

Extension points to reach for first: service providers in app/Providers/ (bindings, view composers, Blade component registration), published config files, and the Blade component directory. These are the seams the kit author intended; editing shipped views and controllers directly is the seam you'll regret at rebase time.

Debugging a "kit behaves oddly" issue: confirm you cleared caches, confirm you're not looking at a published-but-stale config copy in config/ shadowing the package default, and check git log/git diff against your scaffold commit to rule out local drift. With a small single-maintainer project, an issue you assume is upstream is often your own uncommitted edit.