> For the complete documentation index, see [llms.txt](https://lunarie.gitbook.io/lunarie-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lunarie.gitbook.io/lunarie-docs/desenvolvimento/04-padroes-de-desenvolvimento.md).

# Padrões de Desenvolvimento

> **Última atualização:** 08/10/2026 Regras seguidas no código, com a configuração ou a decisão que as sustenta. Conferidas em `tsconfig.json`, `.prettierrc`, `eslint.config.js` e nos ADRs.

## Ferramentas

| Ferramenta    | Configuração                                                                                                                                 |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| TypeScript    | Modo `strict`, alvo ES2022. `noUnusedLocals` e `noUnusedParameters` estão desligados.                                                        |
| Prettier      | Linha de 100 caracteres, ponto e vírgula, aspas duplas e vírgula final.                                                                      |
| ESLint 9      | Regras recomendadas do JS e do TypeScript, mais regras dos hooks do React e do Prettier. `@typescript-eslint/no-unused-vars` está desligada. |
| Regra própria | O pacote `server-only` é proibido. Código só de servidor usa o sufixo `*.server.ts` ou a marca de `@tanstack/react-start/server-only`.       |

Comandos: `npm run lint`, `npm run format` e `tsc` para tipos.

## Estilo e design

* **Tokens, nunca cores soltas.** Cores, raios e tamanhos de texto vêm dos tokens de `styles.css`. Cor fixa em `style={{}}` não tem exceção (ADR-026).
* **Componentes compartilhados antes de elementos crus.** Botão, campo, diálogo e selo usam os componentes de `components/ui` (ADR-047). Confirmações usam o `ConfirmDialog`, e nunca `window.confirm`.
* **Raio de 4 px** nos controles e containers (ADR-033).
* **Componentes novos ganham story** no Storybook, que usa o componente real e só descreve (ADR-079). Nem todo componente existente tem story.

## Dados e regras

* **Regra crítica no banco.** Triggers e RLS valem mesmo contra chamadas diretas à API.
* **Normalizações no JavaScript do app.** O backfill reaproveita a mesma função. Replicar a regra em SQL cria chaves divergentes.
* **Nunca persistir URL assinada.** Guardar o caminho e assinar sob demanda (ADR-004). A exceção é a URL pública das capas (ADR-011).
* **Migrações idempotentes** sempre que possível (`if not exists`, `drop if exists`) e nomeadas.
* **Função nova de Edge exige um passo novo** em `deploy-edge-functions.yml`.
* **Google Books só pelo proxy** `google-books`, com chave de API (ADR-073).

## Segurança

* Segredos só em variáveis de ambiente (Supabase, Lovable e GitHub Actions). Nunca em código, chat ou commit.
* Funções de administração usam o bearer `ADMIN_SECRET_KEY`. Funções de pessoa validam o JWT e conferem `user.id`.
* Toda mudança de schema é seguida da consulta aos Security Advisors do Supabase.
* Detalhes em [Segurança](/lunarie-docs/arquitetura/05-seguranca.md).

## Desempenho

* Rotas pesadas são divididas em `*.lazy.tsx` (ADR-048).
* Bibliotecas grandes (`jszip`, `pdf-lib`) são importadas sob demanda.
* Chamadas à IA e ao Google Books respeitam limites de cota e repetem com espera quando o serviço pede (ADR-039 e ADR-071).

## Texto

* Textos de interface seguem o [Tom de Voz](/lunarie-docs/marca/04-tom-de-voz.md), com linguagem neutra.
* Em código, nomes de domínio ficam em português (`livro`, `usuario_id`), como no banco.

## Documentos relacionados

* [Organização do Código](/lunarie-docs/desenvolvimento/02-organizacao-do-codigo.md)
* [Padrões de Interface](/lunarie-docs/experiencia-do-usuario/04-padroes-de-interface.md)
* [Testes](/lunarie-docs/desenvolvimento/05-testes.md)