Migrar para o Stack Elinsa

Principio

Fontes de Verdade

1. Repositorio oficial, quando acessivel: https://github.com/elinsa-do-brasil/site
2. Checkout local do site, quando existir.

3. references/elinsa-stack-contract.md

   como baseline quando o repo Elinsa nao estiver acessivel.

package.json

components.json

app/globals.css

components/frontend-shell.tsx

app/(frontend)

node_modules/next/dist/docs/

Workflow

1. Inventarie o projeto original: telas, rotas, fluxos, dados, auth, dependencias, assets, tecnologia e estado de versionamento.
2. Se nao houver Git/GitHub confiavel ou o app vier de ZIP/Lovable/no-code, leia

   references/setup-versioning.md

   e crie o repositorio antes de refatorar.
3. Leia o contrato de stack em

   references/elinsa-stack-contract.md

   .
4. Use a decision tree abaixo para escolher superficie, persistencia, auth e referencias adicionais.
5. Escreva um plano curto: rota final sugerida, arquivos a criar/editar, dependencias a remover, dados/auth a migrar e validacoes.
6. Migre uma tela funcional primeiro. Nao comece por landing page explicativa.
7. Substitua auth legado por Better Auth e persistencia legado por Drizzle/PostgreSQL quando o projeto tiver usuarios, permissoes ou banco.
8. Recrie formularios com shadcn Field, React Hook Form, Zod e resolver.
9. Valide Git, pnpm, Biome, build e fluxos manuais.
10. Prepare README, branch/PR GitHub, checklist e evidencias para revisao da TI.

Decision Tree

• Sem Git, sem GitHub, ZIP, pasta local ou Lovable: carregue

  references/setup-versioning.md

  antes de editar codigo.
• Sem acesso ao repo Elinsa: carregue

  references/elinsa-stack-contract.md

  e copie os contratos base.
• Sistema operacional interno, como almoxarifado, pedidos, cadastros, aprovacoes ou consultas: use Drizzle/PostgreSQL, Better Auth e paginas operacionais. Nao adicione Payload/Fumadocs por padrao.
• Conteudo gerenciavel, vagas, imprensa ou documentacao do site: considere Payload/Fumadocs somente se o dominio pedir ou se a TI aprovar.
• Rota publica institucional: planeje

  app/(frontend)/(publico)/<rota>/page.tsx

  .
• Portal interno: planeje

  app/(frontend)/portal/<rota>/page.tsx

  e respeite o shell existente.
• Conta, login ou configuracoes de usuario: planeje

  app/(frontend)/(conta)/<rota>/page.tsx

  .
• Mutacoes chamadas pela propria UI React: prefira Server Actions co-localizadas ao fluxo ou modulo de dominio. Use Route Handlers apenas quando houver webhook, upload/download protegido, integracao externa, cliente nao React, callback de auth ou necessidade explicita de endpoint HTTP.
• Formulario migrado: carregue

  references/forms.md

  .
• UI, layout, tokens, shadcn ou responsividade: carregue

  references/ui-patterns.md

  .
• Auth, permissoes, banco, emails ou integracoes: carregue

  references/auth-and-data.md

  .
• Entrega, validacao, aceite ou antipadroes: carregue

  references/delivery-checklist.md

  .

Referencias Sob Demanda

• references/setup-versioning.md

  : instalacao de Git/Node/pnpm, Lovable/ZIP, commit inicial, GitHub e branch de migracao.

• references/elinsa-stack-contract.md

  : baseline de package/runtime,

  components.json

  ,

  biome.json

  e

  app/globals.css

  .

• references/migration-process.md

  : inventario, traducao de tecnologias antigas, escolha de superficie, extracao tecnica e assets.

• references/ui-patterns.md

  : shadcn, Tailwind v4, tokens, acessibilidade e composicao visual Elinsa.

• references/forms.md

  : formularios com shadcn Field, React Hook Form, Zod, resolver e validacao server-side.

• references/auth-and-data.md

  : Better Auth, Drizzle/PostgreSQL, permissoes, Payload/Fumadocs, Resend e segredos.

• references/delivery-checklist.md

  : validacao, README, PR para TI, criterios de aceite e antipadroes.

next-best-practices

shadcn

drizzle-best-practices

better-auth-best-practices

payload

resend

webapp-testing

Contratos Duros

• Versione o original antes da migracao quando nao houver historico confiavel.
• Entregue repositorio GitHub privado, branch ou pull request. ZIP, pasta solta, deploy ou link do Lovable nao bastam.
• Use pnpm como unico package manager.
• Use Node 26+, Next.js 16+, React 19+, Tailwind 4+, Biome, shadcn/radix, Better Auth e Drizzle/PostgreSQL como baseline minimo quando o repo Elinsa nao estiver acessivel.
• Prefira Server Actions para mutacoes acopladas a UI. Nao crie uma malha de

  app/api/*

  para CRUD interno sem necessidade real.
• Versione alteracoes de banco com migrations Drizzle commitadas em

  lib/db/migrations

  ou no caminho usado pelo repo. Nao altere schema manualmente no banco como estado final.
• Quando o repo Elinsa estiver acessivel, use as versoes e configuracoes dele como fonte primaria.
• Nao mantenha PHP, WordPress, Vue, Angular, React Router, Firebase Auth, JWT caseiro ou outro runtime legado como dependencia de producao.
• Nao comite

  .env

  , tokens, credenciais, dumps sensiveis ou arquivos pessoais.

Saida Esperada

• O que foi inventariado e qual superficie Elinsa foi escolhida.
• Quais referencias desta skill foram usadas.
• Link ou estado do repositorio/branch/PR GitHub, quando aplicavel.
• Mudancas principais de stack, UI, auth, dados e formularios.
• Comandos de validacao executados e resultados.
• Pendencias claras para a TI revisar ou integrar.