Nuvraxis/nuvraxis-plugins

Biome

Biome é o único formatador e linter para JS, TS, JSX, JSON e CSS. SCSS é a exceção: Biome 2.5 não o analisa, então o stylelint cuida de .scss (veja scss-bem). Sem ESLint, sem Prettier.

O biome.json raiz do template é a fonte da verdade. Um hook do plugin executa pnpm exec biome check --write <file> após cada arquivo que Claude edita, quando um biome.json existe acima dele.

Regras

1. Um biome.json raiz, com esquema fixado na versão instalada. "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json" e @biomejs/biome fixado na mesma versão no catálogo do workspace. Um esquema incompatível oculta opções desconhecidas ou renomeadas no editor. Ao atualizar, execute pnpm exec biome migrate --write e atualize ambos.

2. Deixe o git decidir o que é ignorado: vcs.useIgnoreFile: true. Em seguida, force a ignorar artefatos de build com !! em files.includes (!!**/.next, !!**/.turbo, !!**/dist, !!**/coverage), o que também impede o Biome de escanear essas pastas. Um único ! exclui do processamento mas ainda indexa. files.ignoreUnknown: true evita que .scss e outros arquivos não suportados sejam reportados.

3. Formatador: 2 espaços, largura 100, LF, aspas duplas, ponto e vírgula, trailing commas. Essas opções são fixas para todo repositório para que os diffs não briguem sobre estilo. Não adicione overrides de formatação por pacote.

4. Linter: preset: "recommended", a11y: "error", domínios react e next em recommended. rules.recommended: true é a grafia antiga e está obsoleta: use rules.preset. a11y em error porque o nuvui cuida da acessibilidade de seus próprios componentes, então o que sobra (alt, rótulos, tipos de botão em seu próprio markup) deve estar correto. O domínio next adiciona regras como noImgElement; o react adiciona regras de hooks.

5. Nursery permanece desligado. Regras do nursery mudam entre versões de patch e podem quebrar o CI em uma atualização do Biome. Ative uma deliberadamente, pelo nome, com um comentário explicando o motivo, e reavalie a cada atualização.

6. noConsole avisa, permitindo error e warn. Logs de erro estruturados (instrumentation.ts) usam console.error; console.log solto é capturado.

7. Ordene imports com o assistente, não manualmente. assist.actions.source.organizeImports: "on". biome check --write o aplica; biome ci falha em imports não ordenados.

8. Overrides por glob, para arquivos de teste e afins. O template habilita o domínio test apenas para *.test.ts(x) / *.test-d.ts. Coloque outras diferenças de tipo de arquivo lá também, não em configurações separadas.

9. Configurações aninhadas apenas para pacotes que realmente diferem, e elas estendem a raiz.

   // packages/legacy-widget/biome.json
   { "extends": "//", "linter": { "rules": { "style": { "noNonNullAssertion": "off" } } } }
   

   "extends": "//" significa "a configuração raiz" e implica "root": false. Qualquer outra configuração aninhada deve definir "root": false. Não usamos um pacote @repo/biome-config compartilhado: o arquivo raiz mais // cobre tudo sem necessidade de build ou dependência.

10. Localmente biome check --write; no CI biome ci. pnpm lint executa biome check . (sem escrita); pnpm lint:fix executa biome check --write .. O CI executa pnpm exec biome ci --reporter=github ., que nunca escreve, falha em formatação, lint e ordem de imports, e anota o PR. Adicione --changed --since=origin/main apenas se a execução completa ficar lenta; hoje é questão de milissegundos.

11. Suprima uma linha, com um motivo.

    // biome-ignore lint/suspicious/noExplicitAny: callback de terceiros tipado como any no upstream
    

    Nunca desabilite uma regra em todo o repositório para fazer um arquivo passar. Se uma regra está errada para o repositório, altere biome.json em seu próprio commit com o motivo.

12. Corrija, não silencie, os comuns.

    • useImportType: execute a correção; é exigido por verbatimModuleSyntax.
    • noExplicitAny: use unknown e faça parse (veja typescript-production).
    • useButtonType, noSvgWithoutTitle, useAltText: bugs reais de acessibilidade.
    • noImgElement: use next/image.
    • useExhaustiveDependencies: corrija a lista de dependências ou mova o valor para fora do componente.

13. VS Code: Biome é o formatador padrão, correções ao salvar. O .vscode/settings.json do template define editor.defaultFormatter: "biomejs.biome", source.fixAll.biome e source.organizeImports.biome ao salvar, e biome.requireConfiguration: true para que a extensão fique silenciosa em repositórios sem Biome. SCSS mantém a extensão stylelint. Recomende ambas em .vscode/extensions.json.

14. Migrando de ESLint/Prettier: migre e depois exclua. Veja references/migration.md. Estado final: nenhum pacote eslint*, prettier* ou @typescript-eslint/*, nenhum .eslintrc*, eslint.config.*, .prettierrc*, .prettierignore.

O que o Biome não cobre

Arquivo	Ferramenta
.scss	stylelint (scss-bem)
.yaml (workflows, Helm)	actionlint para workflows; helm lint + kubeconform para charts
.md	nada é imposto
Erros de tipo	tsc --noEmit (pnpm typecheck)

Verificar

pnpm lint                               # biome check . && stylelint
pnpm exec biome ci --reporter=github .  # o que o CI executa
pnpm exec biome rage                    # exibe a configuração resolvida se algo parecer ignorado

Fontes

• https://biomejs.dev/reference/configuration/
• https://biomejs.dev/guides/big-projects/
• https://biomejs.dev/linter/domains/
• https://biomejs.dev/linter/rules/
• https://biomejs.dev/reference/cli/
• https://biomejs.dev/reference/vscode/
• https://biomejs.dev/guides/migrate-eslint-prettier/
• https://biomejs.dev/internals/language-support/