Shared Biome configuration

Linting, formatting and import sorting with Biome 2.

Installation

pnpm add -D @mkappelhof/biome-config @biomejs/biome

Create a biome.json in the root of your project, next to .gitignore:

{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "extends": ["@mkappelhof/biome-config"]
}

Add scripts to package.json:

{
  "scripts": {
    "lint": "biome check .",
    "lint:fix": "biome check --write ."
  }
}

Monorepos

Only the root biome.json extends this package. Nested configs in workspace packages inherit from the root:

{
  "root": false,
  "extends": "//"
}

Without git

The config reads .gitignore, and Biome looks for it next to biome.json. If your project has no .gitignore there, turn VCS integration off:

{
  "extends": ["@mkappelhof/biome-config"],
  "vcs": { "enabled": false }
}

Deterministic framework rules

Biome turns on React/Next.js/Astro/test-runner rules by sniffing your dependencies, so lint behavior can shift when you add or remove a package without touching biome.json. To pin it down instead, set linter.domains explicitly in your project's biome.json:

{
  "extends": ["@mkappelhof/biome-config"],
  "linter": {
    "domains": {
      "react": "recommended",
      "next": "recommended",
      "astro": "recommended",
      "test": "recommended"
    }
  }
}

The astro domain only catches .astro-specific lint rules (e.g. conflicting set:html/children directives). Formatting and parsing .astro files at all requires html.experimentalFullSupportEnabled (already on in this config — see below), since Biome treats Astro as an HTML-superset language.

Only set the domains that apply to your project; "none" turns a domain off entirely. This isn't the default in @mkappelhof/biome-config itself, since the shared config is also used by plain Node projects that shouldn't get React/Next rules.

Editor

Install the Biome extension for your editor and make it the default formatter. For VS Code, put this in .vscode/settings.json:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

What's included

• Files: everything Biome supports (JS/TS/JSX, JSON, CSS, SCSS, Markdown, YAML, HTML, GraphQL), except files in .gitignore and dist, build, out, coverage, .next, .astro, .vercel and .turbo.
• Formatter: 2 spaces, 100-character lines, single quotes, semicolons, ES5 trailing commas. An .editorconfig takes precedence.
• Linter: the recommended preset, plus these rules as errors:
  • JS/TS: noExplicitAny, noConsole, noUnusedImports, noUnusedVariables, useImportType, useExportType, useNodejsImportProtocol, useConsistentArrowReturn and useBlockStatements (no braceless if (x) return;/if (!x) throw ...; — its fix is unsafe, so run biome check --write --unsafe to apply it). noConsole is off again in *.config.*, scripts/** and bin/** files.
  • CSS/SCSS: useGenericFontNames, noInvalidDirectionInLinearGradient, noInvalidGridAreas, noInvalidPositionAtImportRule, noMissingVarFunction, noUnknownMediaFeatureName, noUnknownProperty, noUnknownPseudoClass, noUnknownPseudoElement, noUnknownTypeSelector, noUnknownUnit, noUnmatchableAnbSelector, noDeprecatedMediaType, noDuplicateAtImportRules, noDuplicateCustomProperties, noDuplicateFontNames, noDuplicateProperties, noDuplicateSelectorsKeyframeBlock, noEmptyBlock, noEmptySource, noImportantInKeyframe and noIrregularWhitespace — these are every rule Biome 2.6+ ships with a direct equivalent to @mkappelhof/stylelint-config's rule set (stylelint-config-standard + stylelint-config-recommended-scss), most already in the recommended preset but pinned explicitly here.
  • Framework rules (React, Next.js, tests) are turned on automatically based on your dependencies — see below to pin them explicitly instead.
• HTML: experimentalFullSupportEnabled is on, so Biome formats full HTML/Astro templates rather than only the parts it previously supported.
• Imports: sorted into groups: Node/Bun built-ins, React, packages/aliases, then stylesheets and SVGs, each after a blank line.

Pairing with Stylelint

As of Biome 2.6, SCSS support is no longer limited to CSS Modules — Biome fully parses, formats and lints .scss files, and files.includes matches them by default (no opt-in needed). If the project also uses @mkappelhof/stylelint-config, the two tools will now process the same files unless you stop one of them: exclude style files from this config's files.includes in the project's biome.json ("!**/*.css", "!**/*.scss"), or don't point Stylelint at files Biome already covers.

@mkappelhof/stylelint-config still covers more ground — SCSS-specific checks (scss/* rules, @use/@mixin/@include correctness) and most stylistic rules (empty-line conventions, color notation, quoting, etc.) that Biome's CSS linter doesn't have an equivalent for yet — so for new SCSS-heavy projects, or any project not yet on Biome 2.6+, keep using it instead of relying on Biome alone.

AI agents

This package ships an AGENTS.md that describes the conventions this config enforces. Reference it from your project's AGENTS.md:

- Follow `node_modules/@mkappelhof/biome-config/AGENTS.md`