Search by

marekmiklusek / laravel-starter-kit-react

marekmiklusek

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

Statistics

Installs: 23

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

v1.4.4 2026-11-16 17:53 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:

๐Ÿ“‹ Requirements

  • PHP: see the php constraint in composer.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 both mysql and mariadb connections.
  • In config/essentials.php, models are unguarded by default via Unguard::class => true. This allows mass assignment without explicitly defining $fillable properties. 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:

  1. Install PHP dependencies via Composer
  2. Create .env file from .env.example (if not exists)
  3. Generate application key
  4. Run database migrations
  5. Install NPM dependencies
  6. 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

  1. Create lang/{locale}.json with the same keys as lang/en.json.
  2. Create lang/{locale}/ and translate auth.php, pagination.php, passwords.php, validation.php.
  3. 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 transaction
  • apiResponseNamespaces: 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.php is tested in tests/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/Dtos and app/Enums are flat, ambiguous class names (Config, Item, Service, ...) are not allowed
  • Validation rules always have both min: and max:
  • 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 setup
  • composer dev - Run all development services
  • composer dev:ssr - Run with server-side rendering
  • composer lint - Fix code style issues
  • composer test - Run full test suite
  • composer test:unit - Run Pest tests only
  • composer test:types - Run PHPStan analysis
  • composer test:type-coverage - Check type coverage
  • composer test:lint - Validate code style
  • composer ci:check - Run all CI checks (lint, format, types, tests)

๐Ÿ“ฆ NPM Scripts

  • npm run dev - Start Vite dev server
  • npm run build - Build for production
  • npm run build:ssr - Build for production with SSR
  • npm run lint - Fix frontend lint issues
  • npm run lint:check - Check frontend lint issues
  • npm run format - Format frontend code with Prettier
  • npm run format:check - Check frontend formatting
  • npm run types:check - Check TypeScript types

๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.