Analyzer Suppressions

Purpose and Scope

Analyzer suppressions are the mechanism Biome users reach for when a diagnostic is intentionally not useful at a specific location. In the official user model, the analyzer is the foundation shared by the linter and Assist, so the same suppression engine can disable a lint rule, an assist action, or a syntax diagnostic for a line, a file, or a range. This page explains that model first, then maps the parts that are visible in this repository slice: analyzer configuration, linter rule configuration, assist configuration, and the JavaScript clients that can invoke analyzer-backed operations.

Sources: crates/biome_configuration/src/analyzer/mod.rs, crates/biome_configuration/src/analyzer/linter/mod.rs, crates/biome_configuration/src/analyzer/assist/mod.rs

A suppression is not the same thing as turning a rule off in configuration. Configuration changes the analyzer policy for the workspace, while a suppression is local source-code intent attached to a diagnostic category. If a team disables a rule in configuration, Biome no longer evaluates that rule as enabled for matching files. If a team keeps the rule enabled and adds a suppression comment near a known exception, the code continues to document why the exception exists and other files still receive diagnostics from the same rule or action.

The official syntax starts with a directive such as biome-ignore, biome-ignore-all, biome-ignore-start, or biome-ignore-end, followed by a category such as lint, assist, or syntax. The category can be narrowed with a group and rule or action name, for example lint/suspicious/noDebugger, and some rules can accept a value in parentheses. The final explanation is part of the contract: suppressions should state why the analyzer result is intentionally ignored, not merely that the warning is inconvenient.

Relevant Source Files

• crates/biome_configuration/src/analyzer/mod.rs - Defines the shared analyzer configuration concepts used by rule configuration, severity levels, rule options, filters, domains, categories, and fix kinds.
• crates/biome_configuration/src/analyzer/linter/mod.rs - Defines LinterConfiguration, including enablement, rules, include globs, domains, and validation diagnostics for deprecated rule configuration fields.
• crates/biome_configuration/src/analyzer/assist/mod.rs - Defines AssistConfiguration, including enablement, actions, include globs, and accessors used by analyzer-backed assist behavior.
• packages/@biomejs/js-api/src/index.ts - Exposes the JavaScript Biome API, the Configuration and Diagnostic types, and distribution selection for WebAssembly-backed clients.
• packages/@biomejs/backend-jsonrpc/src/index.ts - Creates a JSON-RPC workspace client connected to a daemon-backed Biome binary and initializes it with client information.
• packages/tailwindcss-config-analyzer/src/types.ts - Defines Tailwind analyzer support types such as candidate rules, variants, and contextual values that can feed analyzer behavior in integrations.

Suppression Model

Biome’s suppression categories line up with analyzer responsibilities. A lint suppression targets diagnostics emitted by linter rules. An assist suppression targets analyzer actions, which may be source actions or code actions presented through the command line or editor tooling. A syntax suppression targets syntax diagnostics. The important design point is that users do not need to learn a separate suppression vocabulary for each tool: the analyzer category and optional group or rule path are the targeting mechanism, and the directive type describes the scope.

The configuration source reinforces this shared model by placing linter and assist under the analyzer configuration namespace rather than treating them as unrelated products. The analyzer module imports assist actions, re-exports linter structures, and depends on common analyzer concepts such as rule options, rule category, rule domain, rule filter, fix kind, and plugin group. That means suppression targeting should be understood as part of a broader analyzer contract: diagnostics and actions are categorized, rules may carry options, and consumers can filter or configure behavior without changing every language integration separately.

Sources: crates/biome_configuration/src/analyzer/mod.rs

The linter configuration describes the workspace-level side of the same decision. LinterConfiguration includes an optional enabled flag, a rules object, analyzer include globs, and rule domains whose values can be all, recommended, or none. Those fields answer the question, “Should this diagnostic family run for this workspace or path?” Suppressions answer the narrower question, “Should this otherwise enabled diagnostic be ignored here?” Keeping those questions separate helps teams avoid turning local exceptions into global policy.

Sources: crates/biome_configuration/src/analyzer/linter/mod.rs

Assist has a parallel configuration surface. AssistConfiguration includes an optional enabled flag, an optional actions object, include globs, and helper methods that return whether assist is enabled and which actions are active. Because official documentation states that linter and assist share the suppression engine, a local suppression can be used for assist actions in the same conceptual way as lint rules. That is especially useful when an automated action is usually desirable, but one occurrence needs to remain unchanged for compatibility or readability reasons.

Sources: crates/biome_configuration/src/analyzer/assist/mod.rs

System-to-Code Mapping

User concept	Source-backed implementation surface	Practical meaning
Analyzer category	RuleCategory and analyzer imports in crates/biome_configuration/src/analyzer/mod.rs	Suppression categories such as lint and assist correspond to analyzer-classified diagnostics or actions.
Lint rule policy	LinterConfiguration.rules, domains, and includes in crates/biome_configuration/src/analyzer/linter/mod.rs	Workspace configuration controls which rules run before local suppressions are considered.
Assist action policy	AssistConfiguration.actions, enabled, and includes in crates/biome_configuration/src/analyzer/assist/mod.rs	Assist behavior is analyzer-backed and can be enabled or constrained separately from lint rules.
Rule options	RuleConfiguration<T> and RuleWithOptions<T> handling in crates/biome_configuration/src/analyzer/mod.rs	A rule can have severity and options; some suppressions may also target supported values documented by the rule.
API diagnostics	Diagnostic union type in packages/@biomejs/js-api/src/index.ts	JavaScript consumers receive diagnostics through the selected WebAssembly distribution.
Workspace clients	createWorkspace and createWorkspaceWithBinary in packages/@biomejs/backend-jsonrpc/src/index.ts	Daemon-backed clients initialize a workspace that can request analyzer-related operations.

The Rust configuration model is the strongest source-backed entry point for understanding how suppressions fit into Biome. RuleConfiguration<T> can be a plain level or a level with options, exposes methods to test whether a rule is enabled, and has merge behavior that allows severity overrides without discarding existing options. That matters when diagnosing suppression behavior: a rule might be active because it was enabled through a preset, domain, group, or explicit rule configuration, and a local suppression then targets the emitted diagnostic by category path.

Sources: crates/biome_configuration/src/analyzer/mod.rs

Rule configuration validation also affects how teams reason about suppression cleanup. The linter configuration validator reports diagnostics when the deprecated recommended field is used and warns if it appears together with preset. Those are configuration diagnostics, not source-code rule diagnostics, but they show the same diagnostics infrastructure being used to guide users toward current analyzer policy. A suppression comment should not be used as a substitute for correcting invalid or deprecated configuration because configuration validation is about project setup rather than a specific source exception.

Sources: crates/biome_configuration/src/analyzer/linter/mod.rs

The Tailwind configuration analyzer types illustrate how analyzer inputs may be richer than a single syntax tree. TailwindContext carries a candidate rule map, variant offsets, and a variant provider, while candidate metadata can include layer, sort index, and optional values. For suppression users, the lesson is that a diagnostic category may be produced after framework-aware analysis rather than a simple token check. For contributors, it shows why suppressions need stable category paths: framework services and rule-specific options can change internal analysis, but the user-facing suppression target must remain understandable.

Sources: packages/tailwindcss-config-analyzer/src/types.ts

Execution Flow for Users

A good suppression workflow starts by reading the diagnostic category. Official rule pages publish categories such as lint/a11y/noNoninteractiveElementInteractions; that full path tells you the category, group, and rule name to use when writing a targeted suppression. Prefer the narrowest useful target. A file-wide biome-ignore-all lint may silence unrelated future problems, while biome-ignore lint/a11y/noNoninteractiveElementInteractions explains that only one accessibility rule is intentionally ignored at that location.

When deciding between configuration and suppression, ask whether the exception is local, repeated, or policy-level. A local false positive or compatibility workaround is a suppression candidate. A rule that the project never wants should be configured through the linter rules surface. A set of files that should not be analyzed should use include or ignore configuration rather than repeated source comments. This separation keeps the analyzer configuration readable and preserves suppressions as source-level documentation for exceptional cases.

For assist actions, use the same reasoning. If an action is generally helpful but one transformation would make a file harder to maintain, a targeted assist suppression communicates that local intent. If the action should not run anywhere in a package, configure assist actions instead. The source-backed configuration model exposes assist enablement and action selection separately from linter enablement, so teams can treat automated actions as their own policy surface while still relying on shared analyzer categories for local exceptions.

Sources: crates/biome_configuration/src/analyzer/assist/mod.rs, crates/biome_configuration/src/analyzer/linter/mod.rs

API Components and Integration Points

The JavaScript API exposes a Biome class whose static create method selects one of three WebAssembly distributions: bundler, Node.js, or web. It also exports the common Configuration and Diagnostic types as unions over those backends. For suppression-aware tooling, this means an integration should pass the same configuration shape that users would write for the analyzer and then inspect returned diagnostics. Suppressed diagnostics should be treated as analyzer output policy, not filtered ad hoc by each JavaScript caller.

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

The JSON-RPC backend offers another integration path. createWorkspace finds the command for the Biome binary and returns null if the platform is unsupported. createWorkspaceWithBinary accepts a command path, creates a socket, wraps it in a transport, sends an initialize request with client information, and returns a workspace wrapper. Editor and daemon integrations that rely on this workspace should preserve the same suppression semantics users see in the CLI, because they are connecting to the Biome workspace service rather than reimplementing analyzer behavior.

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

Compact Reference

• Suppression categories from the official analyzer model: lint, assist, and syntax.
• Suppression directive scopes from the official analyzer model: biome-ignore, biome-ignore-all, biome-ignore-start, and biome-ignore-end.
• Linter configuration entry point: LinterConfiguration with enabled, rules, includes, and domains.
• Assist configuration entry point: AssistConfiguration with enabled, actions, and includes.
• Rule configuration entry point: RuleConfiguration<T> with plain and with-options forms, plus is_disabled, is_enabled, level, set_level, and get_options.
• JavaScript API entry point: Biome.create({ distribution }), where distribution is Distribution.BUNDLER, Distribution.NODE, or Distribution.WEB.
• JSON-RPC API entry points: createWorkspace() and createWorkspaceWithBinary(command).

Implementation Notes and Next Steps

For contributors, the main architectural constraint is that suppressions sit at the boundary between user-authored source text and analyzer-produced categories. Configuration decides which analyzers and actions are active, language and framework services compute diagnostics, and clients surface those diagnostics through CLI, WebAssembly, JSON-RPC, or editor workflows. Any change to rule category naming, assist action naming, or rule option handling can affect suppression precision, so category paths should be treated as user-facing API rather than internal labels.

When debugging a suppression that appears not to work, first verify that the category path matches the diagnostic exactly, including group and rule or action name. Next, check whether the rule is enabled by configuration, preset, domain, or explicit override, because a disabled rule will not produce a diagnostic to suppress. Then confirm the client path: CLI, JavaScript WebAssembly API, and daemon-backed JSON-RPC clients should all be understood as front ends over the analyzer configuration and diagnostic model described here.

Related pages for the broader workflow are configure-biome for workspace analyzer policy, linter-overview-and-rules for rule categories and options, assist-actions for analyzer actions, editors-lsp-daemon for JSON-RPC and editor behavior, and diagnostics-reporters for how diagnostics are represented and displayed. Read those pages next if you are moving from writing suppressions to changing analyzer behavior or integrating Biome into another tool.