OpenWikibiomejs/biome

Diagnostics and Reporters

Purpose and Scope

Biome diagnostics are the structured messages users see when formatting, linting, checking, migrating, or running editor-backed workflows. The official diagnostics reference describes them as more than errors: they can carry information, warnings, tips, and fatal failures, and their severity influences command behavior. A reporter is the presentation layer that turns those diagnostics and command summaries into terminal or machine-readable output. This page connects those reader-facing concepts to the repository surfaces visible in the npm packages and JavaScript integration APIs, so tool authors can understand where diagnostic objects travel after Biome has produced them.

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

The most important distinction for integrators is between diagnostics as data and reporters as output formats. Diagnostics are typed values returned through APIs or carried over service boundaries. Reporters are selected by the CLI, for example with the official --reporter option, and they decide whether the same diagnostic becomes a rich terminal block, a concise single line, a JSON object, or a CI annotation. The source evidence here does not define every reporter renderer, but it does show the public package boundaries that expose diagnostics to JavaScript and connect external clients to the daemon-backed workspace.

Sources: packages/@biomejs/biome/package.json, packages/@biomejs/backend-jsonrpc/package.json

Relevant Source Files

  • packages/@biomejs/backend-jsonrpc/src/index.ts - Defines the JSON-RPC workspace client entry points that connect to a Biome daemon and initialize the remote workspace transport.
  • packages/@biomejs/js-api/src/index.ts - Exports the JavaScript API Diagnostic type, Configuration type, Distribution enum, and Biome.create factory used by JS consumers of WebAssembly builds.
  • packages/@biomejs/plugin-api/index.js - Guards the plugin package entry point with an intentional error that redirects consumers toward the JavaScript API package when they need the public JS integration surface.
  • packages/@biomejs/backend-jsonrpc/package.json - Publishes @biomejs/backend-jsonrpc as bindings to the JSON-RPC Workspace API of the Biome daemon and declares platform CLI packages as optional dependencies.
  • packages/@biomejs/biome/package.json - Publishes the main @biomejs/biome package, the biome binary, configuration schema, supported toolchain keywords, and platform-specific optional CLI packages.
  • packages/@biomejs/cli-darwin-arm64/package.json - Shows the shape of one platform binary package, restricted to Darwin on arm64 and version-aligned with the main CLI package.

Diagnostic Concepts

A diagnostic has a severity, a category, a message, and often extra context such as labels, source locations, notes, or suggested fixes. The official diagnostics reference emphasizes that fatal diagnostics are reserved for unexpected failures, errors usually make the CLI exit unsuccessfully, warnings should be addressed but do not block execution by themselves, and information diagnostics communicate useful context. Those concepts matter to API users because they should not treat every diagnostic as the same kind of failure. A formatting mismatch, a lint violation, and an internal fatal failure can all be presented as diagnostics, but consumers should preserve severity when showing results or deciding exit behavior.

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

The JavaScript API source exposes diagnostics as a public type rather than as a private implementation detail. It imports Diagnostic from each WebAssembly target package and re-exports a union type that can represent diagnostics produced by the bundler, Node.js, or web build. The same file also exports a union Configuration type, which means a JavaScript consumer can configure Biome and then receive diagnostics through one consistent API surface even though the actual runtime backend differs. This is the key repository-backed contract for application authors embedding Biome without shelling out to the CLI.

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

Reporters are the next layer above that data model. The official reporters reference names output modes such as summary, concise, JSON, JSON pretty, and GitHub. The summary reporter groups parsing errors, formatting needs, and rule or assist violations into compact sections. The concise reporter prints one diagnostic per line with file, range, category, and message. JSON reporters preserve the data for scripts, dashboards, or custom tooling, while GitHub-style output supports continuous integration annotations. These reporter choices are presentation decisions; they should not erase the underlying diagnostic category or severity that downstream consumers may need.

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

Public API Surfaces for Diagnostics

For JavaScript consumers, the primary entry point is the Biome class in the JS API package. The class extends a common implementation over the exported configuration and diagnostic type parameters, and its static factory chooses a runtime distribution. The Distribution enum names three supported WebAssembly client families: bundler, Node.js, and web. The factory dynamically imports @biomejs/wasm-bundler, @biomejs/wasm-nodejs, or @biomejs/wasm-web, then constructs a Biome instance around the selected module. If an unknown distribution value is passed, the factory throws an error instead of silently selecting a fallback.

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

That split is important when building a diagnostic viewer, editor extension, test harness, or browser playground. A Node.js service can use the Node distribution, a web page can use the web distribution, and a bundled application can use the bundler distribution, but all should be prepared to receive the same high-level diagnostic type. The API design keeps the diagnostic consumer code independent from the transport decision. In practice, a wrapper can create the correct Biome instance for its host environment, pass configuration, run analysis or formatting operations exposed by the common layer, and render returned diagnostics with its own reporter.

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

The repository also separates plugin authoring from general JavaScript embedding. The plugin API package entry point immediately throws an error explaining that the package is intended to be used in Biome JavaScript plugins and asks whether the caller meant @biomejs/js-api. That guard is a useful signal for diagnostic tooling authors: if the goal is to run Biome from a JavaScript program and inspect diagnostics, use the JS API package rather than depending on the plugin package as a runtime library. The plugin package is intentionally not the general reporter or diagnostic client interface.

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

Daemon and JSON-RPC Workspace Flow

The JSON-RPC backend package provides another diagnostic transport path: a workspace client connected to a remote daemon. Its package metadata describes it as bindings to the JSON-RPC Workspace API of the Biome daemon, and the source entry point exposes createWorkspace and createWorkspaceWithBinary. The first function discovers the command for the current platform and returns null if the platform is unsupported. The second accepts an explicit command path, creates a socket, wraps it in a transport, sends an initialize request, and finally wraps the transport as a Workspace client.

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

This flow matters for diagnostics because daemon-backed tools must preserve both transport failures and analysis results. A client may fail before any file is checked if no platform command can be found. After a socket and transport are established, the initialize request identifies the client as @biomejs/backend-jsonrpc and passes basic capabilities. Once initialized, the returned workspace client is the boundary through which higher-level operations can request parsing, formatting, linting, or project services and receive structured responses. Reporters built on top of this path should distinguish connection failures from diagnostics produced by Biome itself.

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

The package metadata reinforces how the daemon client finds a usable binary. @biomejs/backend-jsonrpc declares optional dependencies on the same platform-specific CLI packages as the main Biome package, including Windows, Darwin, Linux, arm64, x64, and musl variants. This keeps the JavaScript package portable while allowing installation to select a suitable binary for the host. A diagnostic integration that embeds the daemon client should therefore treat platform package resolution as part of startup, not as part of diagnostic rendering. If startup succeeds, the workspace API can be used consistently across operating systems.

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

Distribution and Reporter Packaging

The main npm package publishes the biome command through its binary field and describes the project as a web toolchain for formatting, linting, and more. It includes the configuration schema, README, licenses, and optional platform CLI packages. Its keywords list the languages and file families users commonly associate with diagnostics and reporters, including JavaScript, TypeScript, JSON, JSONC, JSX, TSX, CSS, and GraphQL. This packaging is the user-facing entry point for reporter selection because the installed command is what accepts options such as the official --reporter argument.

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

Platform packages are deliberately small and constrained. The Darwin arm64 package declares the same version as the main CLI package, requires Node.js at the package level, and restricts installation to darwin and arm64. This pattern lets the top-level package depend optionally on all supported binary targets while package managers install only the compatible one. For diagnostics and reporters, the practical consequence is that scripts can invoke the stable biome command from the main package while the native executable comes from a platform-specific dependency selected during installation.

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

Compact Reference

  • Main command package: @biomejs/biome, version 2.5.1, binary name biome, description Biome is a toolchain for the web: formatter, linter and more.
  • Main package runtime requirement: Node.js >=14.21.3 for the published npm package.
  • Main package optional binary dependencies: Windows x64 and arm64, Darwin x64 and arm64, Linux x64 and arm64, and musl Linux x64 and arm64 packages.
  • JSON-RPC backend package: @biomejs/backend-jsonrpc, version 2.0.55, main entry dist/index.js, description Bindings to the JSON-RPC Workspace API of the Biome daemon.
  • JSON-RPC factory: createWorkspace(): Promise<Workspace | null> discovers a command and may return null when the platform command is unavailable.
  • JSON-RPC factory with explicit binary: createWorkspaceWithBinary(command: string): Promise<Workspace> creates a socket, initializes the transport, and returns a workspace wrapper.
  • JS API exported types: Configuration and Diagnostic, each represented as unions over the bundler, Node.js, and web WebAssembly packages.
  • JS API distribution enum: BUNDLER, NODE, and WEB, used by Biome.create to dynamically import the matching WebAssembly client.
  • Plugin API behavior: importing @biomejs/plugin-api as a normal runtime entry throws and directs consumers toward @biomejs/js-api for the public JavaScript API.

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

Practical Flow for Tool Authors

A tool that wants machine-readable diagnostics should start by choosing its execution boundary. If it is a CLI wrapper, install and invoke @biomejs/biome, then select an official reporter such as JSON or JSON pretty when the output needs to be consumed by another process. If it is an embedded JavaScript application, create a Biome instance from @biomejs/js-api with the distribution that matches the host environment and render the returned Diagnostic values itself. If it needs daemon-backed workspace behavior, create a JSON-RPC workspace and handle startup failures separately from returned diagnostics.

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

When rendering diagnostics yourself, keep the official severity semantics intact. Fatal diagnostics should be surfaced as exceptional failures that may deserve a bug report. Error diagnostics should normally make a check or CI task fail. Warnings should remain visible without being treated as transport errors. Informational diagnostics should provide context without blocking the workflow. Also preserve categories such as lint rule names, parser groups, formatter groups, or assist action names when present, because reporters like summary and concise depend on those categories to group or label output in ways users can act on.

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

Read the CLI Reference page when you need the exact command families that produce diagnostics and the reporter option in day-to-day workflows. Read the Linter Rules and Sources page for rule categories and the analyzer origins of many diagnostics. Read Editors, LSP, and Daemon for long-lived workspace behavior and editor troubleshooting, because daemon startup and transport errors are a different class of failure than diagnostics returned by analysis. For contributors, the Internals and Language Support page gives the broader map of parsers, analyzers, and formatters that generate the diagnostic data consumed by these package surfaces.

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

Ask a question...