Nuvraxis/nuvraxis-plugins

Biome

Biome ist der einzige Formatierer und Linter für JS, TS, JSX, JSON und CSS. SCSS ist die Ausnahme: Biome 2.5 parst es nicht, daher übernimmt stylelint .scss-Dateien (siehe scss-bem). Kein ESLint, kein Prettier.

Die biome.json im Root der Vorlage ist die Quelle der Wahrheit. Ein Plugin-Hook führt pnpm exec biome check --write <file> nach jeder von Claude bearbeiteten Datei aus, sofern eine biome.json im übergeordneten Verzeichnis existiert.

Regeln

1. Eine Root-biome.json, Schema fest an die installierte Version gebunden.
   "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json" und @biomejs/biome auf dieselbe Version im Workspace-Katalog festgelegt. Ein nicht passendes Schema versteckt unbekannte oder umbenannte Optionen im Editor. Führe beim Upgrade pnpm exec biome migrate --write aus und aktualisiere beides.

2. Git entscheiden lassen, was ignoriert wird: vcs.useIgnoreFile: true. Dann Build-Ausgaben mit !! in files.includes erzwingend ignorieren (!!**/.next, !!**/.turbo, !!**/dist, !!**/coverage), was Biome auch davon abhält, diese Ordner zu durchsuchen. Ein einzelnes ! schließt von der Verarbeitung aus, indiziert aber weiterhin. files.ignoreUnknown: true verhindert, dass .scss und andere nicht unterstützte Dateien gemeldet werden.

3. Formatierung: 2 Leerzeichen, Breite 100, LF, doppelte Anführungszeichen, Semikolons, nachfolgende Kommas. Diese sind für jedes Repository festgelegt, damit Diffs nicht über den Stil streiten. Füge keine paketspezifischen Formatierungs-Overrides hinzu.

4. Linter: preset: "recommended", a11y: "error", Domänen react und next auf recommended.
   rules.recommended: true ist die alte Schreibweise und veraltet: Verwende rules.preset. a11y auf error, weil nuvui die Zugänglichkeit seiner eigenen Komponenten selbst regelt; was übrig bleibt (alt, Labels, Button-Typen in deinem eigenen Markup), muss korrekt sein. Die next-Domäne fügt Regeln wie noImgElement hinzu; react fügt Hooks-Regeln hinzu.

5. Nursery bleibt ausgeschaltet. Nursery-Regeln ändern sich zwischen Patch-Releases und können bei einem Biome-Upgrade CI-Builds zum Scheitern bringen. Aktiviere eine nur gezielt, mit Namen, mit einem Kommentar, warum, und überprüfe sie bei jedem Upgrade erneut.

6. noConsole warnt, erlaubt aber error und warn. Strukturierte Fehlerprotokolle (instrumentation.ts) verwenden console.error; vereinzelte console.log-Aufrufe werden erfasst.

7. Importe mit der Assist-Funktion sortieren, nicht von Hand. assist.actions.source.organizeImports: "on". biome check --write wendet es an; biome ci schlägt bei unsortierten Importen fehl.

8. Overrides per Glob, für Testdateien und ähnliches. Die Vorlage aktiviert die test-Domäne nur für *.test.ts(x) / *.test-d.ts. Platziere dort auch andere Dateityp-Unterschiede, nicht in separaten Konfigurationen.

9. Verschachtelte Konfigurationen nur für Pakete, die sich tatsächlich unterscheiden, und sie erweitern die Root.

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

   "extends": "//" bedeutet "die Root-Konfiguration" und impliziert "root": false. Jede andere verschachtelte Konfiguration muss "root": false setzen. Wir verwenden kein gemeinsames @repo/biome-config-Paket: Die Root-Datei plus // deckt alles ab, ohne Build oder Abhängigkeit.

10. Lokal biome check --write; in CI biome ci.
    pnpm lint führt biome check . aus (keine Schreibvorgänge); pnpm lint:fix führt biome check --write . aus. CI führt pnpm exec biome ci --reporter=github . aus, das niemals schreibt, bei Formatierungs-, Lint- und Importsortierungsfehlern fehlschlägt und den PR annotiert. Füge --changed --since=origin/main nur hinzu, wenn der vollständige Durchlauf langsam wird; aktuell dauert es Millisekunden.

11. Eine Zeile unterdrücken, mit Begründung.

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

    Deaktiviere niemals eine Regel repositoryweit, um eine einzelne Datei durchzubekommen. Wenn eine Regel für das Repository falsch ist, ändere biome.json in einem eigenen Commit mit der Begründung.

12. Beheben, nicht unterdrücken, die häufigen.

    • useImportType: Führe die Korrektur aus; sie ist erforderlich durch verbatimModuleSyntax.
    • noExplicitAny: Verwende unknown und parse (siehe typescript-production).
    • useButtonType, noSvgWithoutTitle, useAltText: Echte Barrierefreiheitsfehler.
    • noImgElement: Verwende next/image.
    • useExhaustiveDependencies: Korrigiere die Abhängigkeitsliste oder verschiebe den Wert aus der Komponente heraus.

13. VS Code: Biome ist der Standard-Formatierer, Korrekturen beim Speichern. Die .vscode/settings.json der Vorlage setzt editor.defaultFormatter: "biomejs.biome", source.fixAll.biome und source.organizeImports.biome beim Speichern und biome.requireConfiguration: true, damit die Erweiterung in Repos ohne Biome ruhig bleibt. SCSS behält die stylelint-Erweiterung. Empfehle beide in .vscode/extensions.json.

14. Migration von ESLint/Prettier: migrieren, dann löschen.
    Siehe references/migration.md. Endzustand: Keine eslint*-, prettier*- oder @typescript-eslint/*-Pakete, keine .eslintrc*-, eslint.config.*-, .prettierrc*-, .prettierignore-Dateien.

Was Biome nicht abdeckt

Datei	Werkzeug
.scss	stylelint (scss-bem)
.yaml (Workflows, Helm)	actionlint für Workflows; helm lint + kubeconform für Charts
.md	nichts wird erzwungen
Typfehler	tsc --noEmit (pnpm typecheck)

Verifizieren

pnpm lint                               # biome check . && stylelint
pnpm exec biome ci --reporter=github .  # Was CI ausführt
pnpm exec biome rage                    # Gibt die aufgelöste Konfiguration aus, falls etwas ignoriert erscheint

Quellen

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