laravel-11-12-app-guidelines

Laravel 11/12 App Guidelines

Overview

Apply a consistent workflow for Laravel 11/12 apps with optional frontend stacks, Dockerized commands, and Laravel Boost tooling.

Quick Start

• Read repository instructions first: AGENTS.md. If docs/ exists, read docs/README.md and relevant module docs before decisions.
• Detect the stack and command locations; do not guess.
• Use Laravel Boost search-docs for Laravel ecosystem guidance; use Context7 only if Boost docs are unavailable.
• Follow repo conventions for naming, UI language, docs-first policies, and existing component patterns.

Stack Detection

• Check composer.json, package.json, docker-compose.*, and config/* to confirm:
  • Docker Compose/Sail vs host commands
  • API-only vs full-stack
  • Frontend framework (Inertia/React, Livewire, Vue, Blade)
  • Auth (Fortify, Sanctum, Passport, custom)

Laravel 11/12 Core Conventions

• Use the Laravel 11/12 structure: configure middleware, exceptions, and routes in bootstrap/app.php; service providers in bootstrap/providers.php; console configuration in routes/console.php.
• Use Eloquent models and relationships first; avoid raw queries and DB:: unless truly necessary.
• Create Form Request classes for validation instead of inline validation.
• Prefer named routes and route() for URL generation.
• When altering columns, include all existing attributes in the migration to avoid dropping them.
• Ask before destructive database operations (e.g., reset/rollback/fresh).

API-Only Mode

• Use routes/api.php; avoid Inertia and frontend assumptions.
• Prefer API Resources and versioning if the repo already uses them.
• Follow the repo's auth stack (Sanctum/Passport/custom) and response format conventions.
• Do not require Vite/Tailwind/NPM unless the repo already includes them.

Inertia + React + Wayfinder (if present)

• Use Inertia::render() for server-side routing; place pages under resources/js/Pages unless the repo says otherwise.
• Use <Form> or useForm for Inertia forms; add skeleton/empty states for deferred props.
• Use <Link> or router.visit() for navigation.
• Use Wayfinder named imports for tree-shaking; avoid default imports; regenerate routes after changes if required.

Livewire / Vue / Blade (if present)

• Follow existing component patterns and conventions; do not mix frameworks unless the repo already does.
• Keep UI strings in the repo's expected language.

Tailwind CSS v4 (if present)

• Use @import "tailwindcss"; and @theme for tokens.
• Avoid deprecated utilities; use replacements (e.g., shrink-*, grow-*, text-ellipsis).
• Use gap-* for spacing between items; follow existing dark mode conventions if present.

Testing and Formatting

• Use PHPUnit; generate tests with php artisan make:test --phpunit and prefer feature tests.
• Run the minimal relevant tests (php artisan test <file> or --filter=).
• Run vendor/bin/pint --dirty before finalizing code changes.
• After minimal tests pass, offer to run the full test suite.

Laravel Boost MCP Tools (when available)

• search-docs before changing behavior or using framework features.
• list-artisan-commands to confirm Artisan options.
• list-routes to inspect routing changes.
• tinker for PHP debugging and database-query for read-only DB checks.
• browser-logs to inspect frontend errors.
• get-absolute-url for sharing project URLs.
• See references/boost-tools.md for query patterns and tool usage tips.

Output Expectations

• Preserve existing architecture, structure, and dependencies unless the user explicitly requests changes.
• Reuse existing components and follow local patterns.
• Ask concise clarifying questions when repo guidance is missing or ambiguous.