@mkappelhof/biome-config 0.0.0-stage → 1.0.0

package/AGENTS.md

@@ -0,0 +1,55 @@
+# @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 <files>` does the same for specific files.
+
+Run `pnpm biome check --write` 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; }`.
+
+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.
+
+## Tool boundaries
+
+Biome covers JS/TS/JSON (and HTML, via `experimentalFullSupportEnabled`). If the project also
+lints CSS/SCSS with Stylelint (see `@mkappelhof/stylelint-config`), leave that to Stylelint —
+don't add `**/*.css`/`**/*.scss` to this config's `files.includes` and don't add a Biome CSS
+override to replace it.
+
+Never run `git commit`, create a branch, or push, unless you are explicitly asked to. Leave
+changes as uncommitted/staged working-tree edits and let the user commit, branch and push
+themselves.

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# @mkappelhof/biome-config
+
+## 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,114 @@
-# 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, 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: `noExplicitAny`, `noConsole`, `noUnusedImports`, `noUnusedVariables`, `useImportType`, `useExportType`, `useNodejsImportProtocol` and `useConsistentArrowReturn`. `noConsole` is off again in `*.config.*`, `scripts/**` and `bin/**` files. 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
+
+Biome can format/lint CSS and SCSS, but if the project uses `@mkappelhof/stylelint-config` for
+style files (recommended for SCSS-heavy projects — `@use`, nesting, etc.), don't let both tools
+touch the same files. Either exclude style files from this config's `files.includes` in the
+project's `biome.json`, or just don't point Stylelint and Biome at overlapping globs.
+
+## 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,128 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.15/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",
+      "correctness": {
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error"
+      },
+      "suspicious": {
+        "noConsole": "error",
+        "noExplicitAny": "error"
+      },
+      "style": {
+        "useImportType": "error",
+        "useExportType": "error",
+        "useNodejsImportProtocol": "error",
+        "useConsistentArrowReturn": "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,36 @@
 {
   "name": "@mkappelhof/biome-config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.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.5.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15"
+  },
+  "keywords": [
+    "biome",
+    "lint",
+    "format",
+    "config"
+  ]
 }