Laravel Boost Development Guidelines
Expert guidelines for building Laravel applications following Laravel maintainer-curated best practices. Optimized for Laravel 12, Inertia v2, React 19, Tailwind CSS 4, and modern PHP 8.3 development.
Core Stack
**Backend**: Laravel 12, PHP 8.3, Fortify, Sail**Frontend**: Inertia.js v2, React 19, Tailwind CSS 4, Wayfinder**Testing**: Pest 4, PHPUnit 12**Tooling**: Laravel Pint, ESLint 9, Prettier 3Foundation Rules
Follow Existing Conventions
Examine sibling files for structure, naming, and approach before creating or modifying filesUse descriptive variable and method names (e.g., `isRegisteredForDiscounts`, not `discount()`)Check for existing components to reuse before writing new onesStick to existing directory structure—do not create new base folders without approvalVerification & Testing
Do not create verification scripts when tests already cover functionalityUnit and feature tests are more important than tinker scriptsEvery change must be programmatically tested—write or update tests, then run themFrontend Bundling
If UI changes aren't reflected, user may need to run `npm run build`, `npm run dev`, or `composer run dev`Communication
Be concise—focus on important details rather than explaining obvious conceptsOnly create documentation files if explicitly requestedPHP Guidelines
Constructor Property Promotion
Use PHP 8 constructor property promotion:
```php
public function __construct(public GitHub $github) { }
```
Do not allow empty `__construct()` methods with zero parameters.
Type Declarations
Always use explicit return types and parameter type hints:
```php
protected function isAccessible(User $user, ?string $path = null): bool
{
// ...
}
```
Control Structures
Always use curly braces, even for single-line statements.
Comments & Documentation
Prefer PHPDoc blocks over inline commentsAdd array shape type definitions when appropriateAvoid comments within code unless complexity requires explanationEnums
Use TitleCase for enum keys: `FavoritePerson`, `BestLake`, `Monthly`
Laravel Best Practices
Artisan Commands
Use `php artisan make:` commands to create files (migrations, controllers, models, etc.)Pass `--no-interaction` to ensure non-interactive executionFor generic PHP classes, use `php artisan make:class`Database & Eloquent
Always use Eloquent relationships with return type hintsPrefer `Model::query()` over `DB::`Use eager loading to prevent N+1 query problemsUse query builder only for very complex operationsWhen creating models, also create factories and seedersAPI Development
Default to Eloquent API Resources and API versioningFollow existing application conventions if APIs existControllers & Validation
Always create Form Request classes for validation (not inline validation)Include both validation rules and custom error messagesCheck sibling Form Requests for array vs. string validation styleQueues
Use queued jobs with `ShouldQueue` interface for time-consuming operations.
Authentication & Authorization
Use Laravel's built-in features: gates, policies, Sanctum.
URL Generation
Prefer named routes and the `route()` function over hardcoded URLs.
Configuration
Use environment variables only in config filesNever use `env()` directly outside config filesAlways use `config('app.name')`, not `env('APP_NAME')`Testing Best Practices
Use model factories for test data creationCheck for custom factory states before manual setupUse `$this->faker->word()` or `fake()->randomDigit()` following existing conventionsUse `php artisan make:test [name]` for feature tests, add `--unit` for unit testsMost tests should be feature testsLaravel 12 Structure
Laravel 12 uses a streamlined file structure:
**No** `app/Http/Middleware/` filesUse `bootstrap/app.php` to register middleware, exceptions, and routingUse `bootstrap/providers.php` for application-specific service providers**No** `app/Console/Kernel.php`—use `bootstrap/app.php` or `routes/console.php`Commands in `app/Console/Commands/` auto-registerDatabase Migrations
When modifying a column, include all previously defined attributes or they will be dropped.
Model Casts
Use `casts()` method instead of `$casts` property (follow existing conventions).
Eager Loading Limits
Laravel 11+ allows native eager load limiting:
```php
$query->latest()->limit(10);
```
Inertia.js v2
Core Concepts
Components live in `resources/js/Pages` (unless customized in `vite.config.js`)Use `Inertia::render()` for server-side routing instead of Blade views```php
Route::get('/users', function () {
return Inertia::render('Users/Index', [
'users' => User::all()
]);
});
```
Inertia v2 Features
PollingPrefetchingDeferred propsInfinite scrolling with merging props and `WhenVisible`Lazy loading data on scrollDeferred Props & Empty States
Add animated skeleton loaders when using deferred props.
Forms
Use the `<Form>` component (recommended):
```tsx
<Form {...store.form()}>
<input name="title" />
</Form>
```
Or use `useForm` helper for programmatic control. Available options: `resetOnError`, `resetOnSuccess`, `setDefaultsOnSuccess`.
Laravel Wayfinder
Generates TypeScript functions and types for Laravel routes with full type safety.
Development Guidelines
Use named imports for tree-shaking: `import { show } from '@/actions/...'`Avoid default controller importsRun `php artisan wayfinder:generate` after route changes if Vite plugin isn't installedFeatures
**Route Objects**: `show(1)` → `{ url: "/posts/1", method: "get" }`**URL Extraction**: `show.url(1)` → `"/posts/1"`**HTTP Methods**: `show.get(1)`, `show.post()`, `show.patch()`, etc.**Query Parameters**: `show(1, { query: { page: 1 } })` → `"/posts/1?page=1"`**Query Merging**: `show(1, { mergeQuery: { page: 2, sort: null } })`**Form Support**: `<Form {...store.form()}>` → `action="/posts" method="post"`**Parameter Binding**: Detects route keys like `{post:slug}`**Named Routes**: Import from `@/routes/` for non-controller routesExample
```typescript
import { show, store, update } from '@/actions/App/Http/Controllers/PostController'
show(1) // { url: "/posts/1", method: "get" }
show.url(1) // "/posts/1"
show.get(1) // { url: "/posts/1", method: "get" }
// Named routes
import { show as postShow } from '@/routes/post'
postShow(1) // { url: "/posts/1", method: "get" }
```
Laravel Pint (Code Formatting)
Run `vendor/bin/pint --dirty` before finalizing changesDo not run `vendor/bin/pint --test`—simply format the codeTesting Requirements
Test Coverage Enforcement
Every code change must be programmatically testedWrite new tests or update existing testsRun minimum number of tests needed: `php artisan test --filter=YourTest`Ensure tests pass before finalizing changesLaravel Boost MCP Tools
Boost provides powerful tools for this application—use them:
**`list-artisan-commands`**: Check available Artisan commands and parameters**`get-absolute-url`**: Generate correct project URLs with scheme, domain, and port**`tinker`**: Execute PHP to debug or query Eloquent models**`database-query`**: Read from database directly**`browser-logs`**: Read browser logs, errors, and exceptions (recent logs only)**`search-docs`**: Search version-specific documentation for Laravel ecosystem packagesDocumentation Search (`search-docs`)
Critical tool for Laravel, Inertia, Livewire, Filament, Tailwind, Pest, Nova, etc.
**Usage Guidelines:**
Use before making code changes to ensure correct approachAutomatically filters by installed package versionsUse multiple broad, topic-based queries: `['rate limiting', 'routing']`Do not add package names to queries (already filtered)**Search Syntax:**
1. **Simple word searches**: `authentication` → finds 'authenticate', 'auth'
2. **Multiple words (AND)**: `rate limit` → finds both "rate" AND "limit"
3. **Exact phrases**: `"infinite scroll"` → exact position match
4. **Mixed queries**: `middleware "rate limit"` → AND logic with exact phrase
5. **Multiple queries**: `["authentication", "middleware"]` → ANY match
Error Handling
Vite Manifest Error
If you encounter "Unable to locate file in Vite manifest", run `npm run build` or ask user to run `npm run dev` or `composer run dev`.
Workflow
1. **Search documentation** using `search-docs` before implementing features
2. **Check existing files** for conventions (structure, naming, validation style)
3. **Use Artisan commands** to generate files with proper structure
4. **Write or update tests** for every change
5. **Run tests** to ensure they pass
6. **Format code** with `vendor/bin/pint --dirty` before finalizing
7. **Build frontend** if changes aren't reflected in UI