README

Parte do TWS Laravel Starter Kit. O código, as issues e os pull requests ficam no monorepo kelvindk9w/tws-laravel-starter-kit (pasta starters/livewire); este repositório é o espelho só-leitura publicado a cada versão. Documentação: docs/ · Segurança: SECURITY.md · Licença: MIT (LICENSE).

O aplicativo completo do TWS Laravel Starter Kit: painel do usuário em Livewire, super admin em Filament, API v1, filas, backup e o deploy de produção em Docker (docker-compose.prod.yml). Composer: twstec/starter-livewire (projeto).

Telas do kit no pacote: as views das telas do kit (entrada, segundo fator, perfil, contas, chaves de API, webhooks, layouts e componentes do design system) moram no twstec/kit-foundation (resources/livewire, com os nomes de view de sempre). O projeto tem só a página inicial e o dashboard e, para mudar uma tela ou um componente do kit, copia só aquele arquivo para o mesmo caminho em resources/views — o do aplicativo vence. Ver docs/personalizacao.md.

Criar um projeto

Requisitos: PHP 8.4 (extensões intl, bcmath, gd, pcntl, pdo_pgsql ou pdo_sqlite), Composer 2 e Node 24.

composer create-project "twstec/starter-livewire:~2.0" meu-app
# ou, com o instalador do Laravel (as opções a mais são obrigatórias; ver abaixo):
laravel new meu-app --using="twstec/starter-livewire:~2.0" --database=pgsql --phpunit --no-boost

No laravel new, a versão no --using evita o branch de desenvolvimento, o --database igual ao banco escolhido no kit evita a troca do DB_CONNECTION para SQLite e o --phpunit evita a reinstalação do Pest que quebra os testes do kit (o projeto continua no Pest) — detalhes em docs/instalacao.md.

O Composer copia o .env.example para .env, e o post-create-project-cmd chama o instalador (php artisan tws:install --graceful), que num terminal pergunta os módulos opcionais, o banco (PostgreSQL, o padrão, ou SQLite — o modo protótipo) e se o projeto usa Redis (sim, o padrão); gera a APP_KEY e o pepper das chaves de API e configura o Docker de desenvolvimento do projeto (abaixo), em que as migrations rodam no primeiro docker compose up -d. Fora do Docker, aponte o .env para o seu banco e rode php artisan migrate; depois npm ci, npm run build e composer dev. Detalhes em docs/instalacao.md.

Produção: docker compose -f docker-compose.prod.yml up -d --build, com o .env.prod a partir do .env.prod.example. A imagem do app (docker/php/Dockerfile, target prod) instala os pacotes do kit pelo Composer, como qualquer dependência — ver docs/producao.md.

Docker de desenvolvimento (projeto criado)

Um projeto criado a partir deste starter (pelo twstec/kit — com ou sem PHP na máquina — ou pelo create-project acima) já vem com o ambiente de desenvolvimento em Docker: o compose.yaml na raiz e o Dev Container do VS Code em .devcontainer/. O instalador grava no .env o nome do projeto e as portas do número dele (site 808N, e-mails 802N, Vite 803N, banco 804N), o endereço http://<nome>.localhost:<porta> e senhas geradas para o banco e o Redis.

docker compose up -d                          # sobe tudo; o banco e as migrations na primeira vez
docker compose exec app php artisan test      # a suíte, dentro do container
docker compose stop                           # para (os dados ficam)

Sobem o site (nginx + PHP-FPM), o PostgreSQL, o Redis, o Mailpit (os e-mails, em http://<nome>.localhost:802N), a fila, o agendador e o Vite (recarga ao vivo) — com SQLite, sem o PostgreSQL; sem Redis, sem o Redis. Tudo é publicado só em 127.0.0.1; o Redis nunca, o banco só com COMPOSE_PROFILES=db-port no .env. Trocar portas ou o nome: edite o .env e rode docker compose up -d. No VS Code: extensão Dev Containers → "Reopen in Container". Detalhes em docs/instalacao.md. (No monorepo, os dois arquivos ficam em docker/dev/; a publicação os põe no lugar.)

No monorepo

Como instalar, rodar e testar está no CONTRIBUTING.md da raiz do repositório; a documentação por assunto está em docs/. O ambiente de desenvolvimento (docker-compose.yml) fica na raiz do repositório, e os comandos docker compose funcionam também daqui de dentro.

Módulos opcionais. twstec/kit-foundation e twstec/kit-auth vêm sempre; contas e API (twstec/kit-accounts), uploads (twstec/kit-uploads), o /admin (twstec/kit-admin) e os webhooks de saída (twstec/kit-webhooks, tela /webhooks) são opcionais — escolha com php artisan tws:install (pacote twstec/kit-installer, em require-dev). Sem um módulo, as telas, rotas e menus dele somem sozinhos: o aplicativo pergunta Twstec\Kit\Foundation\Kit::has() antes de registrá-los. Ver docs/instalacao.md.

A demonstração do kit (landings em / e /v2, vitrine /ui, contato, catálogo e submissões no /admin, contas demo e massa fictícia) não mora aqui: é o pacote twstec/kit-demo, declarado em require-dev do composer.json. Vem no ambiente de desenvolvimento e não vai para a imagem de produção. Sem ele, / mostra a página inicial mínima do produto (resources/views/home.blade.php). Como tirar: docs/demo.md.

twstec / starter-livewire

Package info

Security

Statistics

README

Criar um projeto

Docker de desenvolvimento (projeto criado)

No monorepo