Biome Setup skill for Codex

Done well means Biome is the only formatter for the files it owns, lint coverage after a migration is known (what was kept, what was dropped, what was replaced), the one-time reformat is a single isolated commit, and biome ci gates pull requests.

Decide first: is Biome the right move?

Situation	Recommendation
New JS/TS project, no strong plugin needs	Biome for lint and format
ESLint + Prettier, mostly core and typescript-eslint rules	Migrate; Biome covers most of them and runs far faster
Heavy reliance on ESLint plugins Biome lacks (custom org rules, niche framework plugins)	Biome as formatter only, keep ESLint for lint; or write GritQL plugins first
Needs full type-aware rules equal to typescript-eslint strictTypeChecked	Keep ESLint for those rules; Biome’s type inference covers some (for example floating promises) but not all
Vue, Svelte, Astro templates	Check current Biome support for the template parts before committing; script blocks are supported, template linting is partial

State the trade-off to the user when rules will be lost. Do not migrate silently.

Inspect

ls biome.json biome.jsonc .eslintrc* eslint.config.* .prettierrc* prettier.config.* .editorconfig 2>/dev/null
npx @biomejs/biome --version 2>/dev/null
grep -nE '"(lint|format|check)' package.json

Read AGENTS.md for the package manager and existing scripts.

Install and initialise

npm install --save-dev --save-exact @biomejs/biome   # pin exact: formatting output changes between versions
npx @biomejs/biome init                               # writes biome.json

Needs network for the install; ask for approval in an offline sandbox.

Reference biome.json

{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true, "defaultBranch": "main" },
  "files": {
    "includes": ["**", "!**/dist", "!**/coverage", "!**/*.generated.ts", "!!**/node_modules"]
  },
  "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
  "javascript": {
    "formatter": { "quoteStyle": "double", "semicolons": "always", "trailingCommas": "all" }
  },
  "linter": {
    "enabled": true,
    "rules": {
      "preset": "recommended",
      "suspicious": { "noExplicitAny": "error" },
      "correctness": { "noUnusedVariables": "error", "noUnusedImports": "error" }
    },
    "domains": { "react": "recommended", "test": "recommended" }
  },
  "assist": { "actions": { "source": { "organizeImports": "on" } } },
  "overrides": [
    { "includes": ["**/*.test.ts", "tests/**"], "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } } }
  ]
}

Key behaviours:

• files.includes is an allow list processed in order; ! excludes from lint and format, !! also stops the scanner from indexing the path (use for huge or vendored directories).
• Without vcs.useIgnoreFile, Biome does not read .gitignore, unlike ESLint and Prettier. Turn it on or build output gets formatted.
• linter.rules.preset (recommended, all, none) replaces the older recommended: true flag; biome migrate --write updates old configs.
• Domains (react, next, solid, test, project, types) switch on rule groups for a framework. project and types make Biome scan dependencies, which costs time.
• The $schema path pointing into node_modules keeps editor validation in sync with the installed version.

Migrating from ESLint and Prettier

npx @biomejs/biome migrate eslint --write                     # rules identical to ESLint originals
npx @biomejs/biome migrate eslint --write --include-inspired  # also rules "inspired by" ESLint ones
npx @biomejs/biome migrate prettier --write                   # writes every formatter option explicitly

• migrate eslint reads the resolved ESLint config (flat or legacy), replaces the linter section of biome.json, sets the preset to none and enables only the mapped rules. Review the output; it reports rules it could not map.
• If it fails with a cyclic reference, comment out plugins and shared configs, migrate, and add their rules back by hand.
• Record coverage before deleting ESLint: list the ESLint rules that produced violations in the last month of CI or on the current tree, and mark each as mapped, replaced by another Biome rule, or dropped.

npx eslint . -f json -o /tmp/eslint.json   # before removing ESLint
node -e 'const r=require("/tmp/eslint.json");const c={};for(const f of r)for(const m of f.messages)c[m.ruleId]=(c[m.ruleId]||0)+1;console.table(c)'

• Formatting: Biome matches Prettier output closely but not byte for byte. Measure churn on a clean tree before committing to it:

npx @biomejs/biome format --write . && git diff --shortstat && git diff --stat | tail -5

If churn is large, check lineWidth, quoteStyle, trailingCommas, arrowParentheses and bracketSameLine against the old Prettier config. Then decide with the user whether to accept the remaining differences.

Daily commands

npx @biomejs/biome check --write .               # format + lint + organize imports, safe fixes
npx @biomejs/biome check --write --unsafe .      # also unsafe fixes; review the diff
npx @biomejs/biome check --staged --write        # pre-commit: staged files only
npx @biomejs/biome check --changed --since=main  # CI on a branch: changed files only
npx @biomejs/biome ci .                          # read-only, CI-friendly reporter, non-zero on any issue
npx @biomejs/biome explain noFloatingPromises    # rule documentation offline

Package scripts:

{ "scripts": { "check": "biome check --write .", "ci:check": "biome ci ." } }

Suppressions need a reason: // biome-ignore lint/suspicious/noExplicitAny: third-party callback. biome-ignore-all (top of file) and biome-ignore-start / biome-ignore-end ranges exist for generated or legacy sections.

Monorepos

Put one biome.json at the root. A package that needs different settings gets its own biome.json with "extends": "//", which inherits from the root and is treated as non-root automatically. Other nested configs must set "root": false. Run Biome from the root; it applies the nearest config per file.

Cut-over workflow

- [ ] 1. Inspect configs; decide full migration vs formatter-only
- [ ] 2. Install pinned Biome; run migrate eslint and migrate prettier
- [ ] 3. Write the rule coverage table (mapped / replaced / dropped)
- [ ] 4. Measure format churn; tune options; get the user's go-ahead
- [ ] 5. Commit config; then commit the reformat alone; add its SHA to .git-blame-ignore-revs
- [ ] 6. Remove ESLint/Prettier packages, configs and editor settings only after CI is green
- [ ] 7. Update scripts, hooks, CI and the editor extension recommendation

Editors: recommend the biomejs.biome VS Code extension and set it as the default formatter for JS/TS/JSON in .vscode/settings.json, with Prettier disabled for those languages, or the two will race on save.

Gotchas

• Not pinning the exact version: a patch release can change formatting and turn CI red on unrelated PRs.
• Forgetting vcs.useIgnoreFile and then reformatting dist/ or vendored code.
• Keeping Prettier in lint-staged or the editor after the switch, so files flip between two formats on every save.
• Treating a quieter lint run as success. Fewer findings after migration usually means rules were dropped; the coverage table is the evidence.
• JSON with comments: name it .jsonc or configure json.parser.allowComments for files like tsconfig.json, which Biome handles as JSONC by known name.

Report: Biome version, rule coverage table, formatting churn (files and lines), removed packages, and new scripts and CI steps.