README

Starter kit Laravel inspirado no Laravel Breeze, com autenticacao via Inertia, Vue e Element Plus.

O pacote instala uma base opinativa para aplicacoes Laravel que usam Vue no frontend, mantendo a simplicidade do Breeze e reaproveitando padroes usados em projetos Kallbuloso.

Recursos

Stack vue com Inertia, Vue 3, Element Plus, Pinia, Ziggy e Vite.
Stack api para autenticacao API com Sanctum.
Stubs compartilhados de autenticacao, testes, controllers, requests e middleware.
Layout autenticado com stores, composables, utilitarios e integracao com Iconify.
Facade Toast para notificacoes flash enviadas pelo backend.
Tooling com ESLint, Prettier, TypeScript e vue-tsc.
Suporte opcional a SSR para Inertia.
Migration de usuario com is_owner, profile_photo_path e softDeletes.
Seeder inicial com usuario de teste.
Senhas com Argon2id, pepper versionado e migracao automatica de hashes legados.
Sessao criptografada, hosts confiaveis e rate limit em camadas para login.
Idioma da aplicacao selecionavel entre en, es, pt e pt_BR, com pt_BR por padrao.

Requisitos

PHP 8.2 ou superior.
Laravel 11, 12 ou 13.
Composer.
Node.js e npm, pnpm, yarn ou bun.

Instalacao Local

Para testar este pacote em uma aplicacao Laravel antes de publicar no Packagist, adicione um repositorio path no composer.json da aplicacao de teste:

"repositories": [
  {
    "type": "path",
    "url": "D:/packages/larakits/breeze-element-plus",
    "options": {
      "symlink": true,
      "versions": {
        "kallbuloso/breeze-element-plus": "1.0.0"
      }
    }
  }
]

Depois instale o pacote:

composer require kallbuloso/breeze-element-plus:^1.0 --dev -W

Tambem e possivel testar diretamente a branch principal:

composer require kallbuloso/breeze-element-plus:dev-main --dev -W

Instalacao Publicada

Quando o pacote estiver publicado, instale com:

composer require kallbuloso/breeze-element-plus --dev

Stack Vue

Para instalar a stack Inertia, Vue e Element Plus:

php artisan breeze-element-plus:install vue

Com SSR:

php artisan breeze-element-plus:install vue --ssr

Com Pest:

php artisan breeze-element-plus:install vue --pest

O instalador copia os stubs, instala dependencias Composer e npm, executa migrate:fresh --seed e prepara os arquivos de frontend.

Depois da instalacao, voce pode rodar:

npm run lint
npm run format
npm run build

Gerador de CRUD

Depois de instalar a stack vue e criar/migrar uma tabela, gere um CRUD baseado no schema existente:

php artisan breeze-element-plus:crud products \
  --group=catalog \
  --group-label="Catálogo" \
  --singular="Produto" \
  --plural="Produtos" \
  --icon=ri:box-3-line

O comando e exclusivo para a stack Vue. Ele gera Model, Form Request, Controller, Factory, Seeder e as paginas Inertia/Vue (Index, Create, Edit, Show e _Form). Tambem registra uma Route::resource, adiciona o item na navegacao e inclui os rótulos no locale frontend ativo.

Executado sem essas opcoes e em modo interativo, o comando pergunta o que nao consegue inferir: confirma o icone sugerido, pede os rótulos singular/plural e lista os grupos de navegacao existentes antes de perguntar em qual o novo CRUD entra. Passe --no-interaction (ou informe todas as opcoes) para gerar sem perguntas.

Grupos de navegacao e rotas

--group e a chave do grupo no menu e o prefixo da rota. Com --group=catalog, o CRUD de products fica em catalog/products com nomes catalog.products.*, aninhado em um grupo de rotas com marcadores estaveis:

Route::middleware(['auth', 'verified'])->group(function () {
    // Route group for Catalog
    Route::group(['prefix' => 'catalog', 'as' => 'catalog.'], function () {
        // breeze-element-plus:crud Product
        Route::resource('products', ProductController::class);
        // /breeze-element-plus:crud Product

        // addGroupRouteCatalog
    });

    // addRoute
});

Os marcadores // addGroupRoute{Grupo} e // addRoute sao os pontos de ancoragem das proximas geracoes: um segundo CRUD no mesmo grupo entra antes de // addGroupRouteCatalog, e um grupo novo entra antes de // addRoute. Sem --group, as rotas ficam no nivel do grupo auth, logo acima de // addRoute. Rodar o comando novamente e idempotente — rotas, navegacao e locale nao sao duplicados.

Configuracao

config/breeze-element-plus.php controla quais colunas o gerador expoe:

'crud' => [
    'form' => ['excluded' => ['id', 'created_at', 'updated_at', 'deleted_at', 'remember_token']],
    'searchable' => ['kinds' => ['string', 'textarea'], 'excluded' => []],
],

searchable.kinds usa os tipos classificados pelo inspetor de schema (string, textarea, integer, decimal, date, datetime, boolean, json, enum, foreign), nao os tipos brutos do banco, entao a mesma configuracao vale para qualquer driver.

Use --dry-run para conferir todas as alteracoes sem escrever arquivos e --force para substituir arquivos gerados que ja existem. Sem --force, arquivos existentes diferentes serao preservados mediante confirmacao. O comando pode receber --skip-format para pular a orientacao de formatacao apos a geracao.

O schema nao revela regras de negocio. Revise os campos de factory, regras de validacao, relacionamentos e controles de formulario antes de usar o resultado em producao. Autorizacao, permissoes, tenancy, migrations, upload de arquivos e carregamento de opcoes para chaves estrangeiras sao propositalmente deixados fora do gerador.

Para desenvolvimento:

npm run start

ou:

npm run dev

Stack API

Para instalar apenas a base API:

php artisan breeze-element-plus:install api

A stack API instala Sanctum, rotas, controllers, requests, testes e a estrutura de autenticacao compartilhada.

Tenancy opcional

Por padrao, a instalacao e single e nao adiciona tabelas, traits ou scopes de tenancy:

php artisan breeze-element-plus:install vue --tenancy=single

Para instalar a base de multitenancy por linhas no mesmo banco de dados, use --tenancy=multi:

php artisan breeze-element-plus:install vue --tenancy=multi
php artisan breeze-element-plus:install api --tenancy=multi

No modo multi, o pacote instala a tabela tenants, adiciona tenant_id ao usuario, cria um tenant para cada novo registro e fornece App\Traits\BelongsToTenant com App\Scopes\TenantScope. Apenas modelos que declarem explicitamente use BelongsToTenant; recebem o filtro global e o preenchimento automatico de tenant_id.

O registro padrao continua exigindo e-mail globalmente unico, mesmo que o schema permita um indice composto por tenant. Nao altere essa regra para permitir o mesmo e-mail em tenants diferentes ate implementar uma identificacao explicita de tenant nos fluxos de login e redefinicao de senha. Onboarding empresarial, selecao de contas, permissions/policies, rotas por dominio e UI de administracao de tenants ficam fora do escopo deste starter kit.

Idiomas

O instalador permite selecionar o idioma preferencial da aplicacao. Em modo interativo, pt_BR aparece como opcao padrao.

Para uma instalacao nao interativa, informe o idioma com --lang:

php artisan breeze-element-plus:install vue --lang=en

Os idiomas disponiveis sao en, es, pt e pt_BR. Se --lang nao for informado em modo nao interativo, sera usado pt_BR. O instalador copia somente o diretorio escolhido para lang/, atualiza APP_LOCALE, APP_FALLBACK_LOCALE e APP_FAKER_LOCALE, e adiciona ao frontend o locale do Element Plus em resources/js/locales/{language}.js e as mensagens da aplicacao em resources/js/locales/{language}/message.js.

Na stack Vue, o idioma visual dos componentes e fornecido pelo locale correspondente do Element Plus. Os textos de autenticacao, perfil, navegacao, tema e layout usam Vue I18n em modo Composition API, com o mesmo idioma fixado durante a instalacao e suporte a renderizacao SSR. A fachada @/locales continua sendo o ponto unico de entrada para o frontend, gerada em resources/js/locales/index.js durante a instalacao.

As traducoes espanholas e portuguesas foram adaptadas dos dados estaticos do Laravel-Lang, distribuido sob licenca MIT. O aviso correspondente esta preservado em stubs/localization/LICENSE-LARAVEL-LANG.

Seguranca de Senhas

Durante a instalacao, o pacote gera um HASH_PEPPER aleatorio de 32 bytes e grava o valor somente no .env. O .env.example recebe apenas a variavel vazia e pode continuar versionado com seguranca.

Os hashes usam Argon2id e recebem um identificador de versao, como v1. Hashes bcrypt ou Argon existentes continuam validos enquanto HASH_ALLOW_LEGACY=true e sao atualizados automaticamente depois de um login bem-sucedido.

Para rotacionar o pepper, mova o identificador e segredo atuais para HASH_PREVIOUS_PEPPERS, defina um novo identificador e gere um novo segredo:

HASH_PEPPER_ID=v2
HASH_PEPPER=novo-segredo
HASH_PREVIOUS_PEPPERS=v1:segredo-anterior

Mais de um pepper anterior pode ser informado, separado por virgula. Mantenha os valores anteriores ate que os hashes ativos tenham sido migrados e execute php artisan config:clear depois de alterar essas variaveis.

O instalador tambem habilita SESSION_ENCRYPT=true. SESSION_SECURE_COOKIE e ativado automaticamente quando APP_URL usa HTTPS; em producao, use sempre uma URL HTTPS e configure TRUSTED_PROXIES apenas com proxies controlados.

Usuario de Teste

O seeder cria um usuario inicial:

E-mail: test@example.com
Senha: password

Esse usuario e criado com is_owner habilitado.

Estrutura Instalada pela Stack Vue

A stack vue adiciona ou atualiza, entre outros:

resources/js/app.js
resources/js/ssr.js, quando --ssr for usado
resources/js/bootstrap.js
resources/js/Components
resources/js/Layouts
resources/js/Pages
resources/js/Stores
resources/js/composables
resources/js/utils/iconify.js
resources/css/app.css
vite.config.js
eslint.config.js
.prettierrc
.prettierignore
.editorconfig

Toast

O pacote mantem uma facade Toast para notificacoes vindas do backend. Exemplo:

use Kallbuloso\BreezeElementPlus\Facades\Toast;

Toast::success('Perfil atualizado com sucesso.');

Os toasts sao compartilhados com o frontend pelo middleware Inertia e exibidos no layout da aplicacao.

Atualizando no App de Teste

Quando alterar este pacote localmente, rode na aplicacao de teste:

composer update kallbuloso/breeze-element-plus -W
php artisan breeze-element-plus:install vue --ssr

Depois:

npm install
npm run lint
npm run format
npm run build

Licenca

Este pacote e open source sob a licenca MIT.

kallbuloso / breeze-element-plus

Maintainers

Package info

Statistics

Security