README

Um starter kit moderno e completo para Laravel 12 com multi-tenancy, Filament Admin, Inertia.js + React, e ferramentas avançadas de produtividade e qualidade de código.

Introdução

Este Starter Kit para Laravel 12 foi pensado para quem quer iniciar um projeto robusto e escalável, já com:

• Frontend Moderno: Inertia.js + React 19 + TypeScript + Tailwind v4
• Admin Panel: Filament v4 completo com recursos administrativos
• Multi-tenancy: Sistema completo de tenants com hosts dedicados
• Autenticação Social: Google e Facebook integrados
• Qualidade de Código: Pint, PHPStan/Larastan, Rector, ESLint, Prettier
• Observabilidade: Logs estruturados, activity tracking, exception monitoring
• Scripts Avançados: Desenvolvimento unificado + QA completa
• CI/CD: GitHub Actions prontos para produção
• Localização: PT-BR incluída

Status: Work in Progress – melhorias contínuas, feedback bem-vindo.

Funcionalidades Incluídas

Core & Infraestrutura

• Laravel 12 com PHP 8.4
• Multi-tenancy completo com models Tenant/TenantHost e middleware dedicado
• Banco SQLite pronto por padrão (criado automaticamente no setup)
• Localização PT-BR completa
• Estrutura de testes robusta (Pest + Playwright para E2E)

Frontend & UI

• Inertia.js 2 + React 19 + TypeScript
• Tailwind CSS 4 com theme system
• Filament 4 Admin Panel completo
• Shadcn UI components para interface consistente
• Livewire 3 para componentes reativos específicos

Autenticação & Permissões

• Autenticação social (Google, Facebook) configurada
• Sistema de permissões com Spatie Laravel Permission
• Sessões persistidas (tabela sessions) com relação ao usuário
• Rate limiting e proteções de segurança

Observabilidade & Monitoramento

• Sentry integrado + contexto enriquecido (app/version/host/user)
• Activity Logs completo com tracking de ações
• Exception tracking e centralização de erros
• Log Viewer interface para visualização de logs
• Tracing simples (Correlation ID / Request ID / X-App-Version)
• Versionamento automático com header X-App-Version via VersionService

Segurança

• Headers de segurança (X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy)
• Middleware de segurança e contexto para Sentry
• Regras de senha fortes em produção
• HTTPS forçado fora do ambiente local

Utilitários & Comandos

• Comandos Artisan adicionais (geração de versão, backup de env, evento de inicialização)
• Helpers personalizados e traits reutilizáveis
• Locale dinâmico do usuário (timezone/locale automático)

Pacotes PHP Instalados

Produção (Core)

• laravel/framework 12 – Core Laravel
• filament/filament 4 – Admin Panel framework completo
• inertiajs/inertia-laravel 2 – Backend Inertia.js
• laravel/wayfinder – Roteamento avançado
• spatie/laravel-permission 6 – Sistema de permissões e roles
• opcodesio/log-viewer 3 – Interface para visualização de logs
• sentry/sentry-laravel 4 – Monitoramento e rastreamento de erros

Desenvolvimento / Qualidade

• barryvdh/laravel-debugbar 3 – Debug de requisições
• barryvdh/laravel-ide-helper 3 – Helpers para autocompletar IDE
• larastan/larastan 3 – Análise estática (PHPStan para Laravel)
• rector/rector 2 + driftingly/rector-laravel – Refactors/upgrades automatizados
• laravel/pint 1 – Padronização de código (PSR / Laravel style)
• laravel/boost 1 – Ferramentas de desenvolvimento Laravel
• laradumps/laradumps 4 – Debug avançado e dump de dados
• lucascudo/laravel-pt-br-localization 3 – Traduções PT-BR
• pestphp/pest 4 + pestphp/pest-plugin-laravel – Testes expressivos
• soloterm/solo – UI/UX de terminal (design system CLI)

Observabilidade / Utilidades Internas

• Middlewares avançados: tracing, segurança, contexto para Sentry, locale do usuário, multi-tenant, terminating
• VersionService para geração e injeção de versão (arquivo VERSION + config + header)
• Activity Logging com models e services dedicados
• Exception Tracking centralizado com Filament interface
• Multi-tenant architecture com Actions pattern

Stack Front-end / Dev

Core Frontend

• React 19 + TypeScript 5
• Inertia.js 2 – Frontend Inertia.js
• Vite 7 + Laravel Vite Plugin
• Tailwind CSS 4
• Laravel Wayfinder – Roteamento avançado

UI Components & Libraries

• Shadcn UI – Sistema de componentes moderno e acessível
• Lucide React – Ícones consistentes
• React Icons – Biblioteca complementar de ícones
• Fontsource Roboto – Tipografia

Qualidade & Ferramentas de Desenvolvimento

• ESLint
• Prettier
• Husky

Testes E2E

• Playwright – Testes end-to-end modernos

Scripts Disponíveis

• npm run dev – Vite em modo desenvolvimento
• npm run build – Build de produção
• npm run format / format:check – Prettier
• npm run lint – ESLint + correções automáticas
• npm run prepare – Configuração Husky

Observabilidade & Versionamento

• Header de resposta: X-Correlation-ID, X-Request-ID, X-App-Version
• Log context enriquecido (app, container, request, user)
• Integração Sentry com escopos/tag de versão e contexto de requisição
• Serviço de versão gera hash curto (git ou variáveis de build) + data + ambiente

Scripts Úteis

Composer - Desenvolvimento

• composer dev – Script principal: Sobe servidor, queue listener, logs em streaming (Pail) e Vite simultaneamente (via concurrently)
• composer test – Executa suite de testes (Pest)

Composer - Quality Assurance (QA)

• composer qa:fix – Correção automática: Executa Pint + Rector
• composer qa:verify – Verificação completa: Pint + Rector + PHPStan + Debug Check + Testes
• composer qa:pint:fix – Executa Laravel Pint (formatação)
• composer qa:pint:test – Testa formatação sem aplicar
• composer qa:pint:bail – Para na primeira falha de formatação
• composer qa:rector:dry – Mostra mudanças do Rector sem aplicar
• composer qa:rector:apply – Aplica refatorações do Rector
• composer qa:stan – Executa PHPStan/Larastan (análise estática)
• composer qa:debug:check – Verifica dumps esquecidos no código
• composer qa:test:ci – Executa testes em modo CI

Comandos Artisan Customizados

• php artisan app:started – Emite evento de inicialização (extensível)
• php artisan system:generate-version – Gera arquivo VERSION
• php artisan system:backup-env – Backup do arquivo .env

NPM - Frontend

• npm run dev – Vite em modo desenvolvimento
• npm run build – Build de produção
• npm run format / format:check – Prettier
• npm run lint – ESLint + correções automáticas
• npm run prepare – Configuração inicial Husky

CI / CD & Automação

GitHub Actions configurados em .github/workflows/:

• tests.yml – Executa a suíte (Pest) em pull requests
• lint.yml – Pint + Prettier (e base para expandir com ESLint / PHPStan)
• dependabot-auto-merge.yml – Auto merge para PRs do Dependabot (quando habilitadas)
• dependabot.yml – Configurado para atualizações de segurança somente

Você pode ajustar facilmente para rodar build de front-end, deploy ou quality gates adicionais.

Como Usar

Instalação Inicial

Crie um novo projeto a partir deste template:

laravel new --using=juniorfontenele/laravel-starter minha-app
cd minha-app

Configuração do Ambiente

1. Configure suas variáveis de ambiente no arquivo .env:

   # Configurações de autenticação social (opcional)
   GOOGLE_CLIENT_ID=your_google_client_id
   GOOGLE_CLIENT_SECRET=your_google_client_secret
   
   # Sentry para monitoramento (opcional)
   SENTRY_LARAVEL_DSN=your_sentry_dsn

2. Instale dependências frontend:

   npm install

Desenvolvimento

Ambiente completo (recomendado):

composer dev

Este comando inicia: servidor Laravel + queue worker + logs + Vite em paralelo.

Apenas frontend:

npm run dev

Apenas backend:

php artisan serve

Testes

# Testes unitários e feature
composer test

# Verificação completa de qualidade
composer qa:verify

# Testes E2E (Playwright)
npx playwright test

Contribuições são bem-vindas via issues ou pull requests.

Licença

Distribuído sob licença MIT.

Se este projeto for útil para você, deixe uma ⭐ no repositório!