@vtex/frontend-lint-biome

VTEX's standard Biome configuration for frontend projects

Introduction

Establishing a standardized format/lint pillar is strategically important for VTEX's frontend organization. This initiative improves Quality Assurance (QA) and aligns with VTEX's global engineering vision of building scalable, high-quality systems. VTEX recommends adopting this configuration as part of the frontend Golden Path.

Standardization also improves engineer mobility: when every project follows the same rules, developers can move between codebases with minimal friction and ramp up faster. In addition, a uniform codebase is essential for effective use of AI tooling—consistent style and patterns give AI assistants a stable foundation to generate and suggest code that matches the rest of the project.

Installation

Install Biome and this configuration package:

pnpm add -D @biomejs/biome @vtex/frontend-lint-biome

Configuration

Create a biome.json file in your project root that extends this configuration:

{
  "extends": ["@vtex/frontend-lint-biome"]
}

NPM Scripts

Add these scripts to your package.json:

{
  "scripts": {
    "lint": "pnpm biome ci",
    "lint:check": "pnpm biome check",
    "lint:check:write": "pnpm biome check --write"
  }
}

CI Integration

You can run Biome at two points: before each commit (locally) and when opening or updating a PR (in CI).

Run on commit (pre-commit)

To run Biome only on staged files before each commit, add the following to your package.json. Use the entry that matches your package manager:

pnpm:

"lint-staged": {
  "*": [
    "pnpm lint:check --staged --no-errors-on-unmatched"
  ]
}

yarn:

"lint-staged": {
  "*": [
    "yarn lint:check --staged --no-errors-on-unmatched"
  ]
}

npm:

"lint-staged": {
  "*": [
    "npm run lint:check -- --staged --no-errors-on-unmatched"
  ]
}

Ensure you have lint-staged and a git hooks manager (e.g. Husky) set up so the lint-staged script runs on pre-commit.

Run on PR (CI/CD)

If your project uses the Node pipeline (CI/CD from Dark Kitchen), the pipeline already runs the lint script. No extra CI configuration is needed for Biome if you followed the recommended scripts above.

Why these standards matter

The sections below give more context on why VTEX invests in code standards and why we use Biome.

Why Code Standards Matter at VTEX

Organizational Consistency

• Unified code style across 70+ frontend developers
• Automatic enforcement of best practices and architectural patterns
• Predictable codebase structure - any developer can navigate any project
• Reduced friction in cross-team collaboration and code sharing

Developer Experience Excellence

• Zero cognitive load on formatting decisions - developers focus on logic
• Instant feedback during development, not during PR reviews
• Seamless onboarding - new team members encounter consistent patterns
• No context switching cost when moving between projects
• IDE consistency - same configuration works everywhere
• Better AI assistance - uniform patterns give AI tools a consistent base to generate and suggest code that fits the project

Operational Efficiency

• Centralized governance - update standards once, propagate everywhere
• Reduced maintenance overhead - single source of truth for configurations
• Simplified migrations - standardized setup enables coordinated upgrades
• Automated compliance - tooling enforces standards without manual reviews
• Faster code reviews - eliminate style discussions, focus on architecture and logic

Business Value

• Accelerated development velocity - less time debating style, more time shipping features
• Higher code quality - consistent enforcement prevents quality degradation
• Reduced technical debt - stop inconsistencies at the source
• Better scalability - new projects inherit battle-tested configurations
• Knowledge transfer - standardization enables effective documentation and training

A pillar transforms 70 individual developers into one cohesive, efficient engineering organization.

Why Biome?

Built in Rust, Biome delivers 98% faster performance than ESLint + Prettier combined, while maintaining high compatibility with both tools. This enables:

• Instant feedback loops during development
• Faster CI/CD pipelines reducing build times
• Better developer experience with near-instant linting and formatting

About the rules and formatter

VTEX's established ESLint/Prettier standards serve as the base for this configuration. These rules have been battle-tested across multiple VTEX projects and represent our organization's code quality requirements. This configuration started from a direct conversion of those legacy standards; it then went through a review that adjusted some rules to improve code quality across VTEX, while keeping migration straightforward for existing projects and leveraging Biome's performance.

Rules reviewed after the direct conversion

The subsections below are the rules that were revised after the direct conversion from legacy ESLint/Prettier. They cover: rules that were too permissive in the legacy config and were raised to at least Biome's minimum recommendation; rules that were set stricter than both the legacy config and Biome recommend; and two special cases that need extra context.

Why some rules are enabled (legacy was more permissive)

Some migrated rules that were too permissive in the VTEX legacy config (e.g. disabled or weaker than Biome’s recommendation) had their severity increased to at least the minimum recommended by Biome, to improve code quality.

rule name — legacy severity → adopted severity (Biome default recommendation).

• useBlockStatements — off → warn
• noNegationElse — off → info
• useArrowFunction — off → warn
• useFragmentSyntax — off → info

Why some rules are stricter than both the legacy config and Biome recommend

Other rules were set to a higher severity than both the legacy config and Biome recommend, to enforce stricter standards at VTEX: rule name — legacy → Biome recommendation → adopted.

• noMagicNumbers — legacy: info → Biome: off → warn (we enable it as warn; in test files — **/*.test.{ts,tsx,js,jsx}, **/*.spec.{ts,tsx,js,jsx}, **/__tests__/** — it is off, because test data often uses arbitrary numbers that are clearly explained by descriptive test names and requiring named constants would reduce test clarity)
• noUselessFragments — legacy: off → Biome: info → warn
• useConsistentArrayType — legacy: warn → Biome: info → warn (syntax: shorthand)
• noUselessCatch — legacy: info → Biome: off → warn
• noNestedComponentDefinitions — legacy: off → Biome: off → error
• noReactPropAssignments — legacy: off → Biome: off → error

Why these two rules are configured as they are (special cases)

useConsistentTypeDefinitions — legacy: off → Biome: info (default: prefer interface) → adopted: info (prefer type). We aligned with Biome’s recommended severity (info) but chose prefer type instead of the default interface. Interfaces support extending, declaration merging, and similar features that matter more for libraries than for applications in general; at VTEX we mostly build applications, not libraries. Types support literal types and other type-level operations that interfaces do not, and those patterns are widely used in our apps. So we standardised on type for application code; interface remains useful for class-related shapes when needed—in those exception cases the rule can be disabled. See also type vs interface and peerigon/eslint-config-peerigon#64.

noImplicitBoolean — legacy: error → Biome: off → adopted: off. We decided to keep it off: it makes the code heavier to read (e.g. requiring disabled={true} instead of disabled), and many VTEX projects had already disabled it.

Where to see the full config

The rules described above (severity refinements and special cases) are defined in the biome.json file in this package. That file also lists every rule that came from the direct conversion of the legacy ESLint/Prettier setup and is not in Biome's recommended set, and the formatter options that differ from Biome's defaults (the formatter follows the legacy (ESLint/Prettier) pattern). For how each rule maps from ESLint/Prettier to Biome, see the ESLint/Prettier to Biome migration guide in the frontend-docs repository.

Additional Resources

• Biome Documentation
• VTEX Biome Migration Guide
• Frontend Golden Path: Linter/Formatter - Biome

Contributing

This package is maintained by the VTEX's Frontend team. For questions or suggestions, please open an issue in the frontend repository.