nwrman/laravel-starter-kit

A fork of nunomaduro/laravel-starter-kit-inertia-react that layers full-stack testing infrastructure, DX tooling, and production-ready React patterns on top of Nuno's ultra-strict, type-safe foundation.

Everything from the upstream kit — 100% type coverage, PHPStan level 9, Rector, strict models via Essentials, Fortify auth, Wayfinder, shadcn/ui — is preserved and kept in sync via git merge upstream/main.

What This Adds

Tech Stack

Getting Started

Requires PHP 8.5+, Bun, and a code coverage driver like Xdebug.

From Packagist (after publishing)

laravel new my-app --using=nwrman/laravel-starter-kit

From local path (development)

laravel new my-app --using=/path/to/laravel-starter-kit

Initial Setup

cd my-app
composer setup    # installs deps, generates key, runs migrations, builds assets
composer dev      # starts queue worker, log watcher, and Vite dev server

Verify Installation

composer test

This runs the full quality suite: type coverage, Pest with 100% code coverage, Vitest, lint checks, and static analysis.

Available Commands

Development

Quality Gates

Targeted Testing

Maintenance

Project Structure (additions over upstream)

resources/js/
  hooks/
    use-inertia-form.ts      # TanStack Form + Inertia bridge with Zod v4
    use-flash-toast.ts        # Inertia flash events -> Sonner toasts
  components/
    error-boundary.tsx        # React error boundary with Inertia awareness
  pages/errors/
    403.tsx                   # Forbidden page
    404.tsx                   # Not Found page
    500.tsx                   # Server Error page
  testing/
    setup.ts                  # Vitest global setup + JSDOM polyfills
    helpers.ts                # Test factories (createUser, createNavItem, etc.)
    mocks/
      inertia.ts              # Full @inertiajs/react mock (usePage, Link, router)
      routes.ts               # Wayfinder route mocks
scripts/
  cloud-build.sh              # Laravel Cloud build with Telegram alerts
  cloud-deploy.sh             # Laravel Cloud deploy with Telegram alerts
.ai/guidelines/               # AI agent coding guidelines (actions, general, vitest)
.github/workflows/tests.yml   # CI: build-once + parallel test lanes
vite.config.ts                # Vite Plus: lint, fmt, staged hooks, plugins
vitest.config.ts              # Separate Vitest config (85% coverage thresholds)

CI Pipeline

The included GitHub Actions workflow (.github/workflows/tests.yml) uses a build-once, test-in-parallel architecture:

build ──┬── php_checks        (Pest + type coverage + 100% code coverage)
        ├── frontend_coverage (Vitest + coverage report)
        └── static_checks    (PHPStan + Rector + Pint + oxlint dry-run)

Optional Telegram notifications fire on start and completion. Configure TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID secrets to enable them — the pipeline works fine without them.

Upstream Sync

This kit is a fork, not a copy. It maintains an upstream remote pointing to nunomaduro/laravel-starter-kit-inertia-react. The mutation surface is deliberately minimal (~13 modified files, ~10 added files) so that upstream merges resolve cleanly:

git fetch upstream
git merge upstream/main

When Nuno updates his kit with new dependencies, components, or security fixes, two commands bring us up to date. Conflicts are limited to the small set of files we both touch (composer.json, vite.config.ts, package.json).

Companion Package

This starter kit includes nwrman/laravel-toolkit as a dev dependency. The toolkit provides Artisan commands (preflight, test:report, test:retry, deploy:notify-telegram) and publishable config stubs (pint.json, rector.php, phpstan.neon, CI workflow).

The toolkit is stack-agnostic — you can use it without this starter kit on any Laravel project:

laravel new my-api --api --pest --no-interaction
cd my-api
composer require --dev nwrman/laravel-toolkit
php artisan toolkit:install

Credits

• Nuno Maduro — upstream starter kit foundation
• Jonathan Hernandez — DX tooling, testing infrastructure, React patterns

License

Open-sourced under the MIT license.