Padrões de Código

TypeScript

• TypeScript 5.9 com strict: true
• noUncheckedIndexedAccess: true — acesso a arrays/objetos retorna T | undefined
• Path alias @/ mapeia para ./src/

Type-checking

Use sempre o script do monorepo:

bun run check-types

Esse script roda tsc -b (build mode com project references) — a única forma confiável de validar tipos cross-package neste repo.

ESLint

• Flat config (ESLint 9+)
• Zero warnings: --max-warnings 0
• Configs por tipo de app:
  • vite — apps/app
  • next-js — apps/docs

bun run lint                    # Lint tudo
bun run lint --filter=app       # Lint só o app

Prettier

Formatação automática para .ts, .tsx e .md:

bun run format

Convenções

Componentes

• shadcn/ui — Importe direto, sem wrappers
• Lucide — Único provider de ícones
• cn() — Para merge de classes

Estrutura de arquivos

src/
├── components/
│   ├── ui/           # shadcn (editável)
│   ├── layout/       # AppLayout, AppSidebar, nav-*
│   └── shared/       # Componentes reusáveis não-domain
├── features/<domain>/
│   ├── components/   # Componentes do domínio
│   └── *Page.tsx     # Páginas (targets de rota)
├── hooks/            # 1 hook por tabela/concern
├── stores/           # Zustand stores
├── lib/              # Utilitários, constantes, supabase
├── providers/        # Context providers
└── routes/           # Router config

Naming

• Componentes: PascalCase (arquivos e funções)
• Hooks: camelCase com prefixo use
• Stores: camelCase com prefixo use e sufixo Store
• Arquivos: kebab-case para hooks e utilitários

Forms

• Use useState por padrão
• Adicione react-hook-form + zod apenas quando a complexidade de validação justificar (3+ regras por campo)

Prefixo App

Reservado para layout shell: AppLayout, AppSidebar, AppHeader.

Padrões de engenharia — a lista completa

As convenções acima são a base. Existe, além delas, um conjunto de regras de engenharia que nasceram de defeito encontrado no código e custaram auditoria para achar. Elas vivem no CLAUDE.md da raiz, seção "Padrões de engenharia", e o CI cobra as automáticas.

O resumo do que elas exigem:

• Erros e estados — toda página com consulta trata o estado de erro com visual distinto do vazio (falha de rede não pode parecer lista vazia); componente que recebe isLoading recebe isError junto; toda mutation tem tratamento de erro com aviso ao usuário; catch que devolve valor padrão loga antes.
• Type-safety — tsconfig novo sempre estende o @repo/typescript-config/base.json; as unknown as X só em fronteira (consulta, RPC, env) e com comentário dizendo quem garante o formato em runtime; tipo de linha de tabela nasce dos tipos gerados, nunca escrito à mão.
• React e TanStack — queryKey copia o formato do hook vizinho do domínio; componente que passa de ~500 linhas é quebrado antes da próxima feature; elemento clicável que substitui navegação ganha suporte a teclado no mesmo commit.
• Código morto — feature termina montada no ponto de entrada real na mesma PR; substituiu uma implementação, apague a antiga; knip limpo antes de abrir PR.
• Backend e runtime — nunca gravar custo ou preço de mentira; toda consulta que alimenta humano ou modelo tem order e limit explícitos; todo fetch externo tem timeout.

Leia a seção inteira no CLAUDE.md antes de abrir a primeira PR — cada item ali existe porque a violação dele já aconteceu neste repositório.