Configure Biome

Purpose and Scope

Biome configuration is the shared contract that keeps the CLI, editors, and programmatic integrations behaving the same way for a project. The official guide describes two sources of configuration: CLI options and a project file named biome.json or biome.jsonc, usually placed near package.json. The repository evidence for this page shows how that contract is distributed to JavaScript users: the published @biomejs/biome package exposes the biome binary and includes configuration_schema.json, while the JavaScript API exports a Configuration type that is shared across WebAssembly builds.

Sources: packages/@biomejs/biome/package.json, packages/@biomejs/js-api/src/index.ts

A useful mental model is that Biome is configured by tool first, and then by language when a language needs specialized behavior. The official configuration guide names the current public tools as formatter, linter, and assist, all enabled by default, with each tool accepting an enabled field. Language-specific configuration is nested under language keys such as javascript, allowing a project to keep general defaults in a tool section while overriding details for one language. This layout matches Biome’s product shape as a web toolchain rather than a single-purpose formatter or linter.

The npm package metadata is an important part of configuration because it determines what a user actually installs before any configuration file is read. @biomejs/biome is described as a toolchain for the web: formatter, linter and more. It publishes the CLI entry point, the generated configuration schema, documentation, licenses, and platform-specific optional dependencies. That means editor integrations and CLI invocations can depend on one package name while npm selects a compatible native binary package for the current operating system and CPU.

Sources: packages/@biomejs/biome/package.json, packages/@biomejs/cli-darwin-arm64/package.json

Relevant Source Files

• packages/@biomejs/biome/package.json — defines the public npm package, biome binary entry, shipped configuration_schema.json, supported keywords, Node engine, and optional native CLI packages.
• packages/@biomejs/js-api/src/index.ts — exports the public Configuration and Diagnostic union types and the Biome.create entry point for WebAssembly-backed JavaScript integrations.
• packages/@biomejs/backend-jsonrpc/src/index.ts — creates a JSON-RPC workspace client, initializes it with client metadata, and wraps the daemon transport as a workspace API.
• packages/@biomejs/backend-jsonrpc/package.json — publishes bindings to the JSON-RPC Workspace API of the Biome daemon and declares the same native CLI optional dependency family used to locate a binary.
• packages/@biomejs/plugin-api/index.js — intentionally rejects direct runtime use and redirects plugin authors toward @biomejs/js-api when they need the JavaScript API.
• packages/@biomejs/cli-darwin-arm64/package.json — represents one platform-specific binary package, constrained to darwin and arm64, used through optional dependency selection.

Configuration File Shape

A minimal Biome configuration file uses top-level tool sections. In the official guide, formatter.enabled, linter.enabled, and assist.enabled can turn individual tools off. This matters because Biome’s main package exposes all of those capabilities through a single binary rather than separate formatter and linter executables. A project can therefore use one checked-in configuration file to coordinate command-line behavior, editor behavior, and automation behavior without asking each environment to remember a long list of flags.

{
  "$schema": "https://biomejs.dev/schemas/2.4.13/schema.json",
  "formatter": { "enabled": true },
  "linter": { "enabled": true },
  "assist": { "enabled": true }
}

The schema reference is not just documentation; it is part of the package contract. The @biomejs/biome package lists configuration_schema.json among the files that are published. That gives downstream tooling, package consumers, and editors a stable artifact to use when validating or completing biome.json and biome.jsonc. In practice, the public schema and the Configuration TypeScript type serve the same reader need in different contexts: JSON users get schema validation, while JavaScript API users get typed configuration input.

Sources: packages/@biomejs/biome/package.json, packages/@biomejs/js-api/src/index.ts

Language-specific settings refine tool-level defaults. For example, the official guide shows a general formatter.indentStyle and formatter.lineWidth, then a JavaScript-specific javascript.formatter.quoteStyle and a JavaScript-specific line-width override. The same structure supports disabling a tool for one language while leaving it enabled elsewhere. This is the core rule for reading Biome configuration: start at the general tool section, then look for a language section that narrows or overrides behavior for the file being processed.

{
  "formatter": {
    "indentStyle": "space",
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "lineWidth": 120
    }
  },
  "json": {
    "formatter": { "enabled": false }
  }
}

JavaScript API and Workspace Configuration Surfaces

The JavaScript API exposes configuration as a type rather than as a file path. packages/@biomejs/js-api/src/index.ts imports Configuration and Diagnostic types from the bundler, Node.js, and web WebAssembly packages, then re-exports a union type that can represent any of those runtime distributions. This is the API-level signal that configuration is intended to be portable across embedding environments. A caller chooses the runtime distribution, creates a Biome instance, and then passes configuration through methods inherited from the common API surface.

Sources: packages/@biomejs/js-api/src/index.ts

The public creation flow is explicit. Distribution has three values: BUNDLER, NODE, and WEB. Biome.create({ distribution }) dynamically imports @biomejs/wasm-bundler, @biomejs/wasm-nodejs, or @biomejs/wasm-web, then constructs the common Biome wrapper. For configuration users, the important point is that the same Configuration type is exported above those distribution choices. A tool author can write one configuration-producing code path, then select the runtime that fits their host environment.

import { Biome, Distribution } from "@biomejs/js-api";
 
const biome = await Biome.create({
  distribution: Distribution.NODE,
});

The daemon-backed JSON-RPC package exposes a different integration route. createWorkspace() locates a command for the current platform and returns null if the platform is unsupported. createWorkspaceWithBinary(command) creates a socket, wraps it in a transport, sends an initialize request with client information for @biomejs/backend-jsonrpc, and returns a workspace wrapper. That workspace layer is where editor-like and service-like consumers can interact with Biome through a long-running process instead of loading WebAssembly directly.

Sources: packages/@biomejs/backend-jsonrpc/src/index.ts, packages/@biomejs/backend-jsonrpc/package.json

Tool-Specific Configuration: Formatter, Linter, Assist, and Rules

Formatter configuration controls layout decisions such as indentation, line width, and language-specific style. The official guide demonstrates the pattern rather than every field: general formatter options apply across languages, then language-specific formatter sections override them. The repository’s package keywords name supported user-facing domains including JavaScript, TypeScript, JSON, JSONC, JSX, TSX, CSS, and GraphQL, which explains why a layered configuration model is preferable to one flat set of formatting options for every file type.

Sources: packages/@biomejs/biome/package.json

Linter configuration follows the same top-level pattern but adds rule selection. Official rule pages show rules under linter.rules, grouped by category; for example, a rule can be configured as linter.rules.nursery.useIncludes with a severity such as error. The important configuration idea is that linter behavior is not only on or off. Projects can enable the linter as a tool, then tune individual rule groups and rule names according to stability, domain, and desired diagnostic severity.

{
  "linter": {
    "rules": {
      "nursery": {
        "useIncludes": "error"
      }
    }
  }
}

Assist configuration belongs beside formatter and linter configuration because assist is treated as a first-class tool in Biome’s public documentation. Assist actions are source actions that can reorganize or improve code, and they need a shared configuration file for the same reason formatter and linter do: a team should not get different editor actions and CLI actions depending on who ran the tool. Keeping assist.enabled at the top level makes that relationship visible to users reviewing a project’s configuration.

Package and Platform Reference

The platform package shown in the evidence, @biomejs/cli-darwin-arm64, is intentionally small and specific. Its package metadata restricts it to macOS on ARM64 through os and cpu fields. The main @biomejs/biome package depends on platform packages optionally, so installation can resolve the right binary without forcing every consumer to download every native build. This detail affects configuration indirectly: the same biome.json should be read by the selected binary regardless of platform.

Sources: packages/@biomejs/biome/package.json, packages/@biomejs/cli-darwin-arm64/package.json

The @biomejs/plugin-api package is also relevant because it prevents a common integration mistake. Its entry point throws immediately with the message that the package is intended for Biome JS plugins and asks whether the caller meant @biomejs/js-api. For readers configuring Biome from JavaScript, this is a clear boundary: use the configuration file for project policy, use @biomejs/js-api for supported programmatic access, and do not treat the plugin package as a general-purpose configuration API.

Sources: packages/@biomejs/plugin-api/index.js, packages/@biomejs/js-api/src/index.ts

Practical Workflow

Start by installing @biomejs/biome in the project and committing a biome.json or biome.jsonc file. Use the schema URL or the packaged schema to get validation while editing. Put shared formatter, linter, and assist settings at the top level, then add language sections only when a language needs a different value. This keeps the configuration readable for teammates who only need to answer three questions: which tools run, which rules or actions are customized, and which languages override the defaults.

When embedding Biome, choose the integration surface based on the host. Use the CLI package when project scripts, CI, and local commands should read the same file. Use @biomejs/js-api when a JavaScript program needs direct WebAssembly-backed access with a typed Configuration. Use @biomejs/backend-jsonrpc when a daemon workspace model is more appropriate, such as an editor or service that benefits from a persistent process. Read next: cli-reference for command behavior, formatter for formatting options, and assist-actions for source actions.