Taming Biome: Override Configuration with Environment Variables

Problem: Configuration Inconsistencies Across Environments

When a team uses Biome to lint and format a JavaScript or TypeScript codebase, the same rules must apply in local development, CI pipelines, and production deployments. A static configuration file works well for local work, but CI environments often need to tweak a few settings (e.g., disabling a rule for a temporary branch) without committing a new file. Manually editing the config for each run is error‑prone and slows down the workflow.

Thesis: Biome’s Environment‑Variable Overrides Let You Keep One Source of Truth

Biome recognises environment variables that start with BIOME_ and uses them to override values in the configuration file. This feature keeps the file clean for the default, while giving you a single, declarative way to change behaviour on the fly. The precedence is:

1. Environment variables (highest)
2. Configuration file (e.g., .biome.json or .biome.yaml)
3. Built‑in defaults

1. The Structure of a Biome Configuration File

Biome’s config is a plain JSON or YAML file placed at the project root. A minimal example looks like this:

{
  "linter": {
    "rules": {
      "no-console": "error",
      "max-line-length": 120
    }
  }
}

Key points:

• The top‑level keys correspond to Biome subsystems (linter, formatter, etc.).
• Each subsystem can contain a rules object where rule names map to severity or options.
• Values are parsed at runtime, so you can mix numbers, strings, booleans, and nested objects.

2. Overriding Rules with Environment Variables

To change a rule without editing the file, set an environment variable that mirrors the path to the rule in the JSON structure, using underscores and uppercase letters. For the example above, to change max-line-length to 80 you would run:

export BIOME_RULES_MAX_LINE_LENGTH=80
biome lint

Biome will read BIOME_RULES_MAX_LINE_LENGTH, parse it as a number, and replace the value from the file. The resulting configuration is as if the file had contained "max-line-length": 80. Nested objects are flattened by prefixing each level with an underscore. For example, to override formatter.lineWidth you would use BIOME_FORMATTER_LINE_WIDTH.

3. Worked Example in a CI Pipeline

Consider a GitHub Actions workflow that runs Biome lint on every push but wants to allow console.log statements in a temporary feature branch. The workflow can set an env var for that branch:

name: Lint
on: [push]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Biome
        run: npm install -g @biomejs/biome
      - name: Run Biome
        env:
          BIOME_LINTER_RULES_NO_CONSOLE: off
        run: biome lint

When BIOME_LINTER_RULES_NO_CONSOLE is set to off, Biome disables the no-console rule for that run, effectively allowing console.log calls. Once the branch is merged, the env var disappears and the rule is enforced again.

4. Trade‑offs and Limitations

• Limited to Top‑Level Keys: The env‑var override syntax only supports a single level of nesting per key. Deeply nested rules require editing the file or writing a custom script.
• Type Conversion: All env‑var values are strings. Biome converts them to the expected type (number, boolean, etc.). If the conversion fails, Biome falls back to the file value and logs a warning.
• Case Sensitivity: On Unix-like systems, env‑var names are case‑sensitive; on Windows they are not. Mixing cases can lead to silent mismatches.
• Documentation Gaps: The official Biome docs list a few supported env vars (e.g., BIOME_LOG_LEVEL), but the full set is not exhaustively documented. Experimentation may be required to discover which rules can be overridden.

5. Actionable Next Steps

1. Install Biome – add it to your project or install globally:

   npm install -D @biomejs/biome
   # or
   npm install -g @biomejs/biome
   

2. Create a Default Config – place a .biome.json or .biome.yaml in the root with your team‑wide rules.
3. Test Env Overrides Locally – set an env var and run biome lint to confirm the rule changes take effect.
4. Integrate into CI – add env‑var overrides to your CI job definitions to toggle rules for specific branches or pull‑requests.
5. Document Override Patterns – maintain a short cheat sheet for the team, listing common overrides and the corresponding env‑var names.
6. Monitor for API Changes – Biome is actively developed. Keep an eye on the changelog and update your scripts when new env‑var support is added or removed.

By leveraging Biome’s environment‑variable overrides you keep a single source of truth in your config file while retaining the flexibility to adapt linting behaviour on the fly. This approach scales from small projects to large monorepos and fits naturally into modern CI/CD pipelines.