Nuvraxis/nuvraxis-plugins

Biome

Biome es el único formateador y linter para JS, TS, JSX, JSON y CSS. SCSS es la excepción: Biome 2.5 no lo procesa, por lo que stylelint maneja .scss (consulta scss-bem). Sin ESLint, sin Prettier.

El biome.json raíz de la plantilla es la fuente de verdad. Un hook del plugin ejecuta pnpm exec biome check --write <archivo> después de cada archivo que Claude modifica, cuando existe un biome.json por encima de él.

Reglas

1. Un único biome.json raíz, con esquema fijado a la versión instalada. "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json", y @biomejs/biome fijado a la misma versión en el catálogo del área de trabajo. Un esquema desajustado oculta opciones desconocidas o renombradas en el editor. Al actualizar, ejecuta pnpm exec biome migrate --write y actualiza ambos.

2. Que git decida qué se ignora: vcs.useIgnoreFile: true. Luego fuerza la ignorancia de la salida de compilación con !! en files.includes (!!**/.next, !!**/.turbo, !!**/dist, !!**/coverage), lo que también evita que Biome escanee esas carpetas. Un solo ! excluye del procesamiento pero aún indexa. files.ignoreUnknown: true evita que .scss y otros archivos no compatibles sean reportados.

3. Formateador: 2 espacios, ancho 100, LF, comillas dobles, punto y coma, comas finales. Estos valores son fijos para cada repositorio para que las diffs no discutan sobre el estilo. No agregues anulaciones de formateador por paquete.

4. Linter: preset: "recommended", a11y: "error", dominios react y next en recommended. rules.recommended: true es la ortografía antigua y está obsoleta: usa rules.preset. a11y en error porque nuvui maneja la accesibilidad de sus propios componentes, por lo que lo que queda (alt, etiquetas, tipos de botón en tu propio marcado) debe ser correcto. El dominio next agrega reglas como noImgElement; react agrega reglas de hooks.

5. Nursery desactivado. Las reglas de nursery cambian entre versiones de parche y pueden romper CI en una actualización de Biome. Activa una deliberadamente, por nombre, con un comentario que indique por qué, y vuelve a verificar en cada actualización.

6. noConsole advierte, permitiendo error y warn. Los registros de error estructurados (instrumentation.ts) usan console.error; los console.log accidentales son detectados.

7. Ordena las importaciones con el asistente, no a mano. assist.actions.source.organizeImports: "on". biome check --write lo aplica; biome ci falla si las importaciones están desordenadas.

8. Anulaciones por glob, para archivos de prueba y similares. La plantilla habilita el dominio test solo para *.test.ts(x) / *.test-d.ts. Coloca allí otras diferencias por tipo de archivo, no en configuraciones separadas.

9. Configuraciones anidadas solo para paquetes que realmente difieran, y extienden la raíz.

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

   "extends": "//" significa "la configuración raíz" e implica "root": false. Cualquier otra configuración anidada debe establecer "root": false. No usamos un paquete compartido @repo/biome-config: el archivo raíz más // lo cubre sin necesidad de compilación ni dependencia.

10. Localmente biome check --write; en CI biome ci. pnpm lint ejecuta biome check . (sin escrituras); pnpm lint:fix ejecuta biome check --write .. CI ejecuta pnpm exec biome ci --reporter=github ., que nunca escribe, falla en formato, linting y orden de importaciones, y anota el PR. Agrega --changed --since=origin/main solo si la ejecución completa se vuelve lenta; hoy es milisegundos.

11. Suprime una línea, con una razón.

    // biome-ignore lint/suspicious/noExplicitAny: third-party callback typed as any upstream
    

    Nunca deshabilites una regla en todo el repositorio para que un solo archivo pase. Si una regla es incorrecta para el repositorio, cambia biome.json en su propio commit con la razón.

12. Corrige, no silencies, las comunes.

    • useImportType: ejecuta la corrección; es requerido por verbatimModuleSyntax.
    • noExplicitAny: usa unknown y analiza (consulta typescript-production).
    • useButtonType, noSvgWithoutTitle, useAltText: errores reales de accesibilidad.
    • noImgElement: usa next/image.
    • useExhaustiveDependencies: corrige la lista de dependencias o mueve el valor fuera del componente.

13. VS Code: Biome es el formateador predeterminado, corrige al guardar. El .vscode/settings.json de la plantilla establece editor.defaultFormatter: "biomejs.biome", source.fixAll.biome y source.organizeImports.biome al guardar, y biome.requireConfiguration: true para que la extensión permanezca inactiva en repositorios sin Biome. SCSS conserva la extensión stylelint. Recomienda ambas en .vscode/extensions.json.

14. Migrando desde ESLint/Prettier: migrar, luego eliminar. Consulta references/migration.md. Estado final: sin paquetes eslint*, prettier* o @typescript-eslint/*, sin .eslintrc*, eslint.config.*, .prettierrc*, .prettierignore.

Lo que Biome no cubre

Archivo	Herramienta
.scss	stylelint (scss-bem)
.yaml (workflows, Helm)	actionlint para workflows; helm lint + kubeconform para charts
.md	nada exigido
Errores de tipo	tsc --noEmit (pnpm typecheck)

Verificar

pnpm lint                               # biome check . && stylelint
pnpm exec biome ci --reporter=github .  # lo que ejecuta CI
pnpm exec biome rage                    # imprime la configuración resuelta si algo parece ignorado

Fuentes

• 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/