marekmiklusek / laravel-starter-kit-react
Laravel React starter kit with code quality tools pre-configured.
Package info
github.com/marekmiklusek/laravel-starter-kit-react
Type:project
pkg:composer/marekmiklusek/laravel-starter-kit-react
Requires
- php: ^8.5
- inertiajs/inertia-laravel: ^3.7.0
- laravel/ai: ^1.4.0
- laravel/fortify: ^1.42.0
- laravel/framework: ^13.42.0
- laravel/tinker: ^3.1.0
- laravel/wayfinder: ^0.1.23
- marekmiklusek/database-backup: ^2.0.3
- marekmiklusek/laravel-slack-errors: ^2.0
- nunomaduro/essentials: ^1.2.0
Requires (Dev)
- driftingly/rector-laravel: ^2.7.3
- fakerphp/faker: ^1.24.1
- larastan/larastan: ^3.15.0
- laravel/boost: ^2.10.4
- laravel/doctor: ^0.1.0
- laravel/pail: ^1.3.0
- laravel/pao: ^1.1.5
- laravel/pint: ^1.32.3
- laravel/sail: ^1.70
- laravel/vet: ^0.2.1
- mockery/mockery: ^1.6.15
- nunomaduro/collision: ^8.9.6
- pestphp/pest: ^5.3.7
- pestphp/pest-plugin-agent: ^5.0
- pestphp/pest-plugin-browser: ^5.2.0
- pestphp/pest-plugin-laravel: ^5.0.1
- pestphp/pest-plugin-phpstan: ^5.3.1
- pestphp/pest-plugin-rector: ^5.0.6
- pestphp/pest-plugin-type-coverage: ^5.1.0
- rector/rector: ^2.8.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v1.4.4
- v1.4.3
- v1.4.2
- v1.4.1
- v1.4.0
- v1.3.26
- v1.3.25
- v1.3.24
- v1.3.23
- v1.3.22
- v1.3.21
- v1.3.20
- v1.3.19
- v1.3.18
- v1.3.17
- v1.3.16
- v1.3.15
- v1.3.14
- v1.3.13
- v1.3.12
- v1.3.11
- v1.3.10
- v1.3.9
- v1.3.8
- v1.3.7
- v1.3.6
- v1.3.5
- v1.3.4
- v1.3.3
- v1.3.2
- v1.3.1
- v1.3.0
- v1.2.7
- v1.2.6
- v1.2.5
- v1.2.4
- v1.2.3
- v1.2.2
- v1.2.1
- v1.2.0
- v1.1.0
- v1.0.1
- v1.0.0
- v0.2.5
- v0.2.4
- v0.2.3
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.7
- 0.1.6
- v0.1.5
- v0.1.4
- v0.1.3
- v0.1.2
- v0.1.1
- 0.1.0
This package is auto-updated.
Last update: 2026-11-16 17:55:55 UTC
README
Laravel's official React starter kit enhanced with development workflow tools, code quality standards, and additional developer experience improvements.
Built with Inertia.js, React, Tailwind CSS, and Laravel Wayfinder.
๐ฆ Bundled Packages
Beyond Laravel's default React stack, this kit ships pre-configured with:
- marekmiklusek/database-backup: automated MySQL backups to local storage or Google Drive (setup)
- marekmiklusek/laravel-slack-errors: unhandled exception notifications to Slack (setup)
๐ Requirements
- PHP: see the
phpconstraint incomposer.json - Composer
- Node.js & NPM
- MySQL (or your preferred database)
๐ Quick Start
Note
- In
config/database.php,'engine' => 'InnoDB',is used as the default for bothmysqlandmariadbconnections. - In
config/essentials.php, models are unguarded by default viaUnguard::class => true. This allows mass assignment without explicitly defining$fillableproperties. You can change this setting if you prefer to use guarded models.
๐ฆ Installation
Create a new Laravel React project:
composer create-project marekmiklusek/laravel-starter-kit-react --prefer-dist app-name
Run the automated setup script:
composer setup
This command will:
- Install PHP dependencies via Composer
- Create
.envfile from.env.example(if not exists) - Generate application key
- Run database migrations
- Install NPM dependencies
- Build frontend assets
โ๏ธ Additional Setup
๐ง Environment Configuration
After running composer setup, configure your .env file with your database credentials:
DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=your_database_name DB_USERNAME=your_username DB_PASSWORD=your_password
๐ Browser Testing Setup (Optional)
If you plan to use Pest's browser testing capabilities, install Playwright:
npm install playwright npx playwright install
This installs the necessary browser binaries for running browser tests.
๐พ Database Backups
The starter kit ships with marekmiklusek/database-backup for automated MySQL backups. The config is already published to config/database-backup.php, no vendor:publish needed.
Backups are stored locally on the local disk in storage/app/private/database-backups, and old backups are cleaned up automatically after 14 days.
A daily backup is already scheduled in routes/console.php:
Schedule::command('db-backup:run') ->dailyAt('02:00') ->onOneServer() ->runInBackground();
Run it manually at any time:
php artisan db-backup:run # create a backup php artisan db-backup:cleanup # delete backups older than the retention period
Adjust the disk, directory, filename pattern, retention period, and mail notifications in config/database-backup.php. To back up to Google Drive instead of (or alongside) local storage, add a google disk to config/filesystems.php and set storage.disk. See the package README for the full Google Drive setup guide.
๐ข Slack Error Notifications
The starter kit ships with marekmiklusek/laravel-slack-errors, which sends unhandled exceptions to a Slack channel through an incoming webhook. No changes to bootstrap/app.php or the exception handler are needed.
Create an incoming webhook for your Slack app, choose the channel, and add the URL to .env (the keys are already present in .env.example):
SLACK_ERRORS_ENABLED=true # default, set to false to disable notifications entirely SLACK_ERRORS_WEBHOOK_URL=your_webhook_url SLACK_ERRORS_ENVIRONMENTS=production # comma-separated list, wildcards allowed
Send a test message to verify the webhook (it ignores the environment filter):
php artisan slack-errors:test
To change the mention, throttling, or ignored exceptions, publish the config to config/slack-errors.php:
php artisan vendor:publish --tag=slack-errors-config
Tip
Nothing is sent while SLACK_ERRORS_WEBHOOK_URL is empty, and only the environments listed in SLACK_ERRORS_ENVIRONMENTS report, so local development stays quiet. Exceptions in your app's dontReport are never sent.
๐ป Development
๐ฅ๏ธ Running the Development Server
Start all development services concurrently:
composer dev
This starts:
- Laravel development server (port 8000) - Your Inertia + React application
- Queue listener - Background job processing
- Vite dev server - Hot Module Replacement for React/CSS/JS
Your application will be available at http://localhost:8000 ๐
SSR Mode
To run with server-side rendering:
composer dev:ssr
๐ Authentication
Creating Users
Users are created via Artisan:
php artisan user:create
The command prompts for the name and email address, validating each answer right away, then generates a random password and prints it once. Created users have their email marked as verified.
๐ Localization
The starter kit ships with full multilingual support. English (en) and Czech (cs) are included out of the box, and every user-facing string in the React frontend goes through the translator.
๐ง Switching the Locale
Set the locale in your .env file:
APP_LOCALE=cs APP_FALLBACK_LOCALE=en APP_FAKER_LOCALE=cs_CZ
After saving, the entire UI (auth pages, settings, dashboard, navigation, validation messages) renders in the selected language. No build step is needed for translation changes; the JSON dictionary is loaded server-side per request.
๐ Language Files
lang/
โโโ en.json # English UI strings (key โ translation)
โโโ cs.json # Czech UI strings
โโโ en/
โ โโโ auth.php # Laravel auth messages
โ โโโ pagination.php
โ โโโ passwords.php
โ โโโ validation.php # Laravel validation messages
โโโ cs/
โโโ auth.php
โโโ pagination.php
โโโ passwords.php
โโโ validation.php
*.json holds the application-level strings keyed by their English source text (Laravel's idiomatic JSON translation format). The PHP files cover Laravel's framework-level messages.
โ๏ธ Using Translations in React
The current locale and translations dictionary are shared as Inertia props by HandleInertiaRequests. Use the useTranslations hook in any component:
import { useTranslations } from '@/hooks/use-translations'; export default function MyComponent() { const __ = useTranslations(); return <h1>{__('Welcome')}</h1>; }
The hook also supports :placeholder interpolation:
__('Hello :name', { name: 'Marek' });
โ Adding a New Language
- Create
lang/{locale}.jsonwith the same keys aslang/en.json. - Create
lang/{locale}/and translateauth.php,pagination.php,passwords.php,validation.php. - Set
APP_LOCALE={locale}in.env.
๐๏ธ Architecture
The kit enforces a small set of architecture rules. They are written down for AI agents in .ai/guidelines/architecture.md and enforced by PHPStan and Pest, so a violation fails composer test.
๐งฑ Layers
| Layer | Location | Create with |
|---|---|---|
| Actions (writes and business logic) | app/Actions |
php artisan make:action "{Name}" --no-interaction |
| Queries (reads) | app/Queries |
php artisan make:query "{Name}" --no-interaction |
| DTOs (structured data between layers) | app/Dtos |
php artisan make:dto "{Name}" --no-interaction |
Controllers, commands, jobs and listeners only validate input, call actions and queries, and return a response.
๐ PHPStan Rules
Custom rules live in tests/PHPStan/Rules and run with composer test:types. Every error message starts with the rule ID and says how to fix it.
| ID | Rule |
|---|---|
| Q1 | Query classes only read data |
| T1 | No side effects (HTTP, API clients, jobs, events, mail, notifications) inside DB::transaction() |
| D1 | Actions and queries never take or return associative arrays, API clients in app/Services never return them |
| C1 | Cache, rate limiter and signed URL expirations are Carbon expressions (now()->addMinutes(15)) |
| A1 | Database writes only in actions |
| R1 | Database reads only in query classes |
| P1 | A private method duplicated across actions is extracted into its own action |
Two rules are configurable in phpstan.neon:
services: - class: Tests\PHPStan\Rules\SideEffectCallDetector arguments: sideEffectClasses: - App\Services\ShoptetClient - class: Tests\PHPStan\Rules\ArrayInsteadOfDtoRule arguments: apiResponseNamespaces: - App\Services
sideEffectClasses: your API clients, so T1 also catches their calls inside a transactionapiResponseNamespaces: where your API clients live, so D1 checks their return values
โ Conventions
Checked by tests/Unit/ArchTest.php and tests/Unit/CodingConventionsTest.php:
- Tests mirror
app/:app/Http/Controllers/Settings/ProfileController.phpis tested intests/Feature/Http/Controllers/Settings/ProfileControllerTest.php, and every action, query, command, controller, middleware, Livewire component, job, listener, service and model has its own test file - Objects are named after their class (
CreateUser $createUser), dates by meaning (CarbonInterface $orderedAt) app/Actions,app/Dtosandapp/Enumsare flat, ambiguous class names (Config,Item,Service, ...) are not allowed- Validation rules always have both
min:andmax: - No mocks in tests and no single-letter variables
Money is never a float. Amounts are stored as integers in the smallest unit (cents) and formatted as decimals only for display.
๐ค AI Guidelines
The kit uses Laravel Boost to generate CLAUDE.md (Claude Code) and AGENTS.md (Codex) from one source:
.ai/guidelines/architecture.md: the kit's architecture rules with the same IDs as the PHPStan errors.ai/guidelines/php/core.blade.php: overrides Boost's PHP guideline (no descriptive comments, type-only PHPDoc)
Kit rules take precedence over conflicting advice in Boost skills. Never edit CLAUDE.md or AGENTS.md directly. Change the guidelines and regenerate them:
php artisan boost:update
boost:update also runs automatically after composer update.
๐ Code Quality
๐งน Linting & Formatting
Fix code style issues:
composer lint
This runs:
- Rector (PHP refactoring)
- Laravel Pint (PHP formatting)
- ESLint & Prettier (frontend formatting)
๐งช Testing
Run the full test suite:
composer test
This includes:
- Type coverage (100% minimum)
- Code coverage (100% required)
- Unit and feature tests (Pest)
- Code style validation
- Static analysis (PHPStan)
๐ Browser Testing
This starter kit includes Pest with browser testing capabilities. Create browser tests in tests/Browser/:
it('displays the login page', function () { $page = visit('/login'); $page->assertSee(__('Log in to your account')) ->assertNoJavascriptErrors(); });
๐ Available Scripts
๐ผ Composer Scripts
composer setup- Initial project setupcomposer dev- Run all development servicescomposer dev:ssr- Run with server-side renderingcomposer lint- Fix code style issuescomposer test- Run full test suitecomposer test:unit- Run Pest tests onlycomposer test:types- Run PHPStan analysiscomposer test:type-coverage- Check type coveragecomposer test:lint- Validate code stylecomposer ci:check- Run all CI checks (lint, format, types, tests)
๐ฆ NPM Scripts
npm run dev- Start Vite dev servernpm run build- Build for productionnpm run build:ssr- Build for production with SSRnpm run lint- Fix frontend lint issuesnpm run lint:check- Check frontend lint issuesnpm run format- Format frontend code with Prettiernpm run format:check- Check frontend formattingnpm run types:check- Check TypeScript types
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.