pantheon-org/nx-biome-integration

Nx Biome Integration

Navigation hub for integrating Biome in Nx workspaces with predictable setup and migration.

When to Use

• You need to add Biome lint and format targets in an Nx workspace.
• You are migrating from ESLint or Prettier to Biome.
• You need Nx cache-friendly Biome task configuration.
• You are creating plugin-based inferred tasks for workspace scale.

Principles

• Prefer one root config unless migration constraints require nested overrides.
• Keep lint and format authority singular for each file path.
• Optimize for deterministic CI (read-only checks) and reproducible local fixes.

When Not to Use

• The repository standard is intentionally ESLint/Prettier-only.
• The task is not Nx-related and does not require workspace task integration.

Workflow

1. Confirm prerequisites: Nx workspace, Node.js 18+, package manager selected.
2. Install Biome and initialize root configuration.
3. Add project targets (or plugin inferred tasks) and enable Nx caching inputs.
4. Validate lint and format execution on one project, then run across workspace.
5. Apply migration strategy (all-at-once or selective nested biome.json).
6. Enforce anti-pattern checks before rollout.

Quick Commands

Install and Initialize

npm install --save-dev @biomejs/biome
npx @biomejs/biome init

Expected: root biome.json exists.

Run on One Project

nx biome-lint my-project
nx biome-format my-project

Expected: lint and format targets execute for the selected project.

Run Across Workspace

nx run-many -t biome-lint
nx run-many -t biome-format

Expected: all configured projects run with consistent config and cache behavior.

Run Through Package Script

bun run nx run-many -t biome-lint

Expected: Biome lint runs through package-managed Nx entrypoint.

Reset Nx State After Plugin Changes

nx reset

Expected: daemon cache is cleared and targets refresh.

Anti-Patterns

NEVER use nested biome.json for simple workspace-wide setups

• WHY: unnecessary config layering increases maintenance and rule drift.
• BAD: create biome.json in every project by default.
• GOOD: use one root config and add nested configs only for migration or real overrides.
• BAD: nested configs everywhere.
• GOOD: root-first config with explicit exceptions.

NEVER run ESLint and Biome on the same files without explicit boundary

• WHY: dual lint pipelines produce conflicting diagnostics and wasted CI time.
• BAD: keep ESLint glob coverage unchanged after adding Biome.
• GOOD: define migration boundaries so each file set has one active lint authority.
• BAD: same files linted twice.
• GOOD: single lint owner per file path.

NEVER omit biome.json and Biome dependency from Nx cache inputs

• WHY: cache hits become stale after config/tool version changes.
• BAD: cache only default and ^default inputs.
• GOOD: include "{workspaceRoot}/biome.json" and externalDependencies: ["@biomejs/biome"].
• BAD: omit config/dependency inputs.
• GOOD: include config and tool-version inputs.

NEVER auto-enable formatter writes in CI verification jobs

• WHY: write-mode formatting in CI mutates files and obscures validation failures.
• BAD: run biome format --write in required CI checks.
• GOOD: use check/lint mode in CI; reserve write-mode for local or dedicated fix jobs.
• BAD: mutating CI verification.
• GOOD: read-only CI checks.

NEVER downgrade critical Biome rules to suppress migration noise

• WHY: suppressing high-signal rules hides real issues and delays stabilization.
• BAD: globally reduce important rules to off during migration.
• GOOD: scope temporary exceptions narrowly with documented expiration.
• BAD: blanket rule disablement.
• GOOD: time-boxed scoped exceptions.

Reference Map

• Deep configuration and cache tuning: references/biome-configuration-deep-dive.md
• Migration from ESLint and Prettier: references/migration-guide.md
• Plugin-based inferred tasks: references/plugin-patterns.md

References

• Biome Docs
• Nx Plugin Docs
• Nx Inferred Tasks
• Biome Big Projects Guide