@mkappelhof/biome-config 0.0.0-stage → 1.1.0

package/AGENTS.md

@@ -0,0 +1,67 @@
+# @mkappelhof/biome-config — agent instructions
+
+This project's `biome.json` extends `@mkappelhof/biome-config`. Biome handles linting, formatting and import sorting, so do not add Prettier or ESLint alongside it.
+
+## Commands
+
+- `pnpm biome check .` lints, checks formatting and checks import order.
+- `pnpm biome check --write .` applies safe fixes, formats and sorts imports.
+- `pnpm biome check --write --unsafe .` also applies unsafe fixes (e.g. `useBlockStatements`
+  wrapping a bare `if (x) return;` in braces). Review the diff — unsafe fixes are low-risk here,
+  not unreviewed.
+- `pnpm biome check --write <files>` (optionally with `--unsafe`) does the same for specific files.
+
+Run `pnpm biome check --write --unsafe` on the files you changed before you finish a task. The task is not done while `pnpm biome check .` reports errors. Files listed in `.gitignore` are skipped.
+
+## Formatting (applied automatically, do not fight it)
+
+- 2-space indentation, LF line endings, 100-character line width. An `.editorconfig` in the project takes precedence.
+- Single quotes, semicolons always, trailing commas where valid in ES5, parentheses around arrow function parameters always.
+- Self-closing void HTML elements (`<br />`).
+
+## Import order
+
+Imports are sorted into these groups, in this order:
+1. Node/Bun built-ins (`node:fs`, `bun:test`)
+2. `react`
+3. URLs, packages and aliases
+4. _(blank line)_ CSS / SCSS imports
+5. _(blank line)_ SVG imports
+
+Let `biome check --write` order imports for you. Do not order them by hand.
+
+## Lint rules
+
+The `recommended` preset is enabled, plus these rules as errors:
+- **No `any`** (`noExplicitAny`). Use `unknown` and narrow it, or write a proper type.
+- **No `console`** (`noConsole`). Use the project's logger, or remove debug output before you finish. Allowed in `*.config.*`, `scripts/**` and `bin/**` files, where logging is normal.
+- **No unused imports or variables** (`noUnusedImports`, `noUnusedVariables`). Prefix intentionally unused variables or parameters with `_`.
+- **Type-only imports and exports use `type`** (`useImportType`, `useExportType`): `import type { Foo } from './foo'` or `import { type Foo, bar } from './foo'`.
+- **Node built-ins use the `node:` prefix** (`useNodejsImportProtocol`): `import { readFile } from 'node:fs/promises'`.
+- **Arrow functions that only return a value use a concise body** (`useConsistentArrowReturn`): `(x) => x * 2`, not `(x) => { return x * 2; }`.
+- **Braceless single-statement bodies are not allowed** (`useBlockStatements`): write `if (!x) { throw new Error(); }`, not `if (!x) throw new Error();` or `if (x) return;`. Applies to `if`/`else`, loops and similar. The auto-fix for this one is unsafe (see Commands above), not unavailable.
+
+Framework-specific rules (React, Next.js, test runners) are turned on automatically based on the dependencies in `package.json`. If the project's `biome.json` sets `linter.domains` explicitly (see its README), treat that as the source of truth instead.
+
+Fix the cause of a diagnostic. Do not add `// biome-ignore` unless there is no reasonable alternative, and always give a reason: `// biome-ignore lint/<group>/<rule>: <reason>`. Do not disable rules or change formatter settings in the project's `biome.json` to get a check to pass.
+
+## CSS/SCSS
+
+Biome 2.6+ fully parses, formats and lints `.scss` files (not just CSS Modules), and
+`files.includes` matches them by default. On top of `recommended`, these are pinned as errors:
+`useGenericFontNames`, `noInvalidDirectionInLinearGradient`, `noInvalidGridAreas`,
+`noInvalidPositionAtImportRule`, `noMissingVarFunction`, `noUnknownMediaFeatureName`,
+`noUnknownProperty`, `noUnknownPseudoClass`, `noUnknownPseudoElement`, `noUnknownTypeSelector`,
+`noUnknownUnit`, `noUnmatchableAnbSelector`, `noDeprecatedMediaType`, `noDuplicateAtImportRules`,
+`noDuplicateCustomProperties`, `noDuplicateFontNames`, `noDuplicateProperties`,
+`noDuplicateSelectorsKeyframeBlock`, `noEmptyBlock`, `noEmptySource`, `noImportantInKeyframe` and
+`noIrregularWhitespace`. Use `// biome-ignore lint/<group>/<rule>: <reason>` the same as for JS/TS,
+not a `/* stylelint-disable */` comment.
+
+## Tool boundaries
+
+Biome covers JS/TS/JSON/CSS/SCSS (and HTML, via `experimentalFullSupportEnabled`). If the project
+also lints CSS/SCSS with Stylelint (see `@mkappelhof/stylelint-config`) rather than relying on
+Biome's CSS rules, the project's own `biome.json` must exclude style files from this config's
+`files.includes` (`"!**/*.css"`, `"!**/*.scss"`) so the two tools don't both process them — check
+there before assuming Biome owns `.scss` files in a given project.

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# @mkappelhof/biome-config
+
+## 1.1.0
+
+### Minor Changes
+
+- 3c4c6b4: Enable `useBlockStatements` so braceless single-statement bodies (`if (!x) throw ...;`, `if (x) return;`) are flagged. Its fix is unsafe, so apply it with `biome check --write --unsafe` rather than plain `--write`.
+- 3c4c6b4: Bump Biome to 2.6.2, which adds full SCSS support (not just CSS Modules) to Biome's own parser, formatter and linter. Pin the CSS/SCSS lint rules that mirror `@mkappelhof/stylelint-config`'s rule set (`noUnknownProperty`, `noDuplicateProperties`, `noEmptyBlock`, etc.) as explicit errors, on top of the `recommended` preset that already covers most of them. `@mkappelhof/stylelint-config` is unchanged and still recommended for SCSS-heavy projects, since Biome's CSS linter doesn't yet cover SCSS-specific or stylistic rules.
+
+## 1.0.1
+
+### Patch Changes
+
+- eb2577f: Add new configs
+
+## 2.0.0
+
+### Major Changes
+
+- 9665a73: Fix and modernise the Biome config:
+  
+  - Respect `.gitignore` (VCS integration enabled). Projects without a `.gitignore` next to `biome.json` must set `"vcs": { "enabled": false }`.
+  - Check every file type Biome supports (CSS, JSX, `.mjs`/`.cjs`, etc.), and also ignore `build`, `out`, `coverage` and `.next`.
+  - Enable `noExplicitAny`, `noConsole`, `noUnusedImports`, `noUnusedVariables`, `useImportType`, `useExportType`, `useNodejsImportProtocol` and `useConsistentArrowReturn` as errors.
+  - Loosen the `@biomejs/biome` peer dependency to `^2.5.0`.
+  - Add an `exports` map (`@mkappelhof/biome-config` and `@mkappelhof/biome-config/biome` both work) and a `files` list, so only the config and docs are published.
+  - Remove the rollup build, which wrote JavaScript into `dist/biome.json`.
+  - Add `AGENTS.md`.
+  - Turn `noConsole` back off for `*.config.*`, `scripts/**` and `bin/**` files.
+  - Document how to pin `linter.domains` explicitly in a consuming project, instead of relying on Biome's dependency-based auto-detection of React/Next/test rules.
+  - Add a fixture-based regression test (`pnpm test`) that checks the config's custom rules and overrides actually fire.
+
+### Patch Changes
+
+- 1eb73de: Add an `astro.json` preset to `@mkappelhof/ts-config`, pulled from how a real Astro site configures
+  TypeScript: Astro's own `strict.json` base plus this package's usual `noUncheckedIndexedAccess`,
+  `noImplicitOverride` and `noFallthroughCasesInSwitch`.
+  
+  Also documents pinning Biome's `astro` lint domain in `@mkappelhof/biome-config`'s README, alongside
+  the existing `react`/`next`/`test` domain guidance.
+- 58ff254: Pull in live configuration learnings from a real project:
+  
+  - `@mkappelhof/biome-config`: enable `html.experimentalFullSupportEnabled`, and document in the
+    `AGENTS.md`/README how to pair this config with `@mkappelhof/stylelint-config` without the two
+    tools overlapping on the same files.
+  - `@mkappelhof/ts-config`: document in `AGENTS.md` that `react.json` projects define path aliases
+    and any extra ambient `types` (e.g. browser-extension globals) in their own `tsconfig.json`.
+  
+  Also adds a new `@mkappelhof/stylelint-config` package (Stylelint config for CSS/SCSS, built on
+  `stylelint-config-standard` + `stylelint-config-recommended-scss`), for projects that pair Biome
+  with Stylelint instead of relying on Biome for styles.
+
+## 1.0.1
+
+### Patch Changes
+
+- 4035554: Add biome config

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# Shared Biome configuration
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Linting, formatting and import sorting with [Biome](https://biomejs.dev) 2.
+
+## Installation
+
+```sh
+pnpm add -D @mkappelhof/biome-config @biomejs/biome
+```
+
+Create a `biome.json` in the root of your project, next to `.gitignore`:
+
+```JSON
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "extends": ["@mkappelhof/biome-config"]
+}
+```
+
+Add scripts to `package.json`:
+
+```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:
+
+```JSON
+{
+  "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:
+
+```JSON
+{
+  "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`:
+
+```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](#whats-included)), 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`:
+
+```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](#deterministic-framework-rules) 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`:
+
+```md
+- Follow `node_modules/@mkappelhof/biome-config/AGENTS.md`
+```

package/biome.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.6.2/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": [
+      "**",
+      "!**/.vscode",
+      "!**/dist",
+      "!**/build",
+      "!**/out",
+      "!**/coverage",
+      "!**/.next",
+      "!**/.astro",
+      "!**/.vercel",
+      "!**/.turbo",
+      "!**/pnpm-lock.yaml"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "formatWithErrors": false,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineEnding": "lf",
+    "lineWidth": 100,
+    "attributePosition": "auto",
+    "bracketSameLine": false,
+    "bracketSpacing": true,
+    "expand": "auto",
+    "useEditorconfig": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "a11y": {
+        "useGenericFontNames": "error"
+      },
+      "correctness": {
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error",
+        "noInvalidDirectionInLinearGradient": "error",
+        "noInvalidGridAreas": "error",
+        "noInvalidPositionAtImportRule": "error",
+        "noMissingVarFunction": "error",
+        "noUnknownMediaFeatureName": "error",
+        "noUnknownProperty": "error",
+        "noUnknownPseudoClass": "error",
+        "noUnknownPseudoElement": "error",
+        "noUnknownTypeSelector": "error",
+        "noUnknownUnit": "error",
+        "noUnmatchableAnbSelector": "error"
+      },
+      "suspicious": {
+        "noConsole": "error",
+        "noExplicitAny": "error",
+        "noDeprecatedMediaType": "error",
+        "noDuplicateAtImportRules": "error",
+        "noDuplicateCustomProperties": "error",
+        "noDuplicateFontNames": "error",
+        "noDuplicateProperties": "error",
+        "noDuplicateSelectorsKeyframeBlock": "error",
+        "noEmptyBlock": "error",
+        "noEmptySource": "error",
+        "noImportantInKeyframe": "error",
+        "noIrregularWhitespace": "error",
+        "noShorthandPropertyOverrides": "error"
+      },
+      "style": {
+        "useImportType": "error",
+        "useExportType": "error",
+        "useNodejsImportProtocol": "error",
+        "useConsistentArrowReturn": "error",
+        "useBlockStatements": "error"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteProperties": "asNeeded",
+      "trailingCommas": "es5",
+      "semicolons": "always",
+      "arrowParentheses": "always",
+      "bracketSameLine": false,
+      "quoteStyle": "single",
+      "attributePosition": "auto",
+      "bracketSpacing": true
+    }
+  },
+  "html": {
+    "experimentalFullSupportEnabled": true,
+    "formatter": {
+      "enabled": true,
+      "selfCloseVoidElements": "always"
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.config.*", "**/scripts/**", "**/bin/**"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noConsole": "off"
+          }
+        }
+      }
+    }
+  ],
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": {
+          "level": "on",
+          "options": {
+            "groups": [
+              [":NODE:", ":BUN:"],
+              "react",
+              [
+                ":URL:",
+                ":PATH:",
+                ":PACKAGE_WITH_PROTOCOL:",
+                ":PACKAGE:",
+                ":ALIAS:",
+                "!**/*.css",
+                "!**/*.scss",
+                "!**/*.svg"
+              ],
+              ":BLANK_LINE:",
+              ["**/*.css", "**/*.scss"],
+              ":BLANK_LINE:",
+              "**/*.svg"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@mkappelhof/biome-config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Shared Biome configuration (linting + formatting)",
+  "main": "biome.json",
+  "exports": {
+    ".": "./biome.json",
+    "./biome": "./biome.json",
+    "./package.json": "./package.json"
+  },
+  "files": ["biome.json", "AGENTS.md", "README.md", "CHANGELOG.md"],
+  "license": "MIT",
+  "repository": "git@github.com:mkappelhof/frontend-tools.git",
+  "author": "Maurice Kappelhof <maurice@mauricekappelhof.nl>",
+  "scripts": {
+    "lint": "biome check --vcs-enabled=false biome.json package.json README.md AGENTS.md",
+    "test": "node test/run.mjs"
+  },
+  "peerDependencies": {
+    "@biomejs/biome": "^2.6.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.2"
+  },
+  "keywords": ["biome", "lint", "format", "config"]
+}