Assist Actions

Purpose and Scope

Assist actions are Biome features that produce code changes rather than only reporting problems. The official Assist documentation frames them as safe, developer-experience-oriented code fixes: they may sort fields, simplify expressions, or perform refactorings, and they are especially useful from editors through LSP code actions. This page maps that public concept to the repository evidence supplied for JSON assist behavior, focusing on useSortedPackageJson, the source action that organizes package.json fields according to established conventions. It also connects that implementation to the npm package metadata that Biome itself publishes, because those manifests show the real file shapes the action is designed to normalize.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs, packages/@biomejs/biome/package.json

The most important distinction for readers is that assist actions are not linter rules with optional fixes. In the official model, an assist action always offers a fix, and enabling assist means asking Biome to make structured edits that improve consistency or reduce manual work. The JSON assist catalog includes source actions such as useSortedKeys and useSortedPackageJson. useSortedPackageJson is more specialized than a plain alphabetical sort: it understands named package manifest fields, nested objects, dependency-like maps, scripts, exports, and tool-specific configuration blocks, then applies the transformation only when the JSON value can be improved.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs

Relevant Source Files

• crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs — Implements the sorter dispatch layer for the JSON useSortedPackageJson assist, including nested pnpm.overrides sorting and the shared try_transform_field function used to decide and apply transformations.
• packages/@biomejs/backend-jsonrpc/package.json — Provides a published package manifest with scripts, files, repository, keywords, engines, devDependencies, publishConfig, and optionalDependencies, making it a concrete example of package fields that can be organized.
• packages/@biomejs/biome/package.json — Defines the main npm package, its bin entry for biome, supported keywords, files, engine requirement, funding metadata, and platform optional dependencies.
• packages/@biomejs/cli-darwin-arm64/package.json — Represents a platform-specific optional CLI package constrained by os: darwin and cpu: arm64.
• packages/@biomejs/cli-darwin-x64/package.json — Represents the Darwin x64 platform package with the same distribution metadata pattern as other native packages.
• packages/@biomejs/cli-linux-arm64-musl/package.json — Represents a Linux arm64 musl platform package and adds a libc constraint to the platform manifest pattern.

Public Assist Model

In user-facing configuration, assist is a top-level Biome tool area alongside formatting and linting. The official docs show an assist block with enabled and actions.source.useSortedKeys, and they describe editor integration through code-action identifiers such as source.fixAll.biome and per-action identifiers like source.action.useSortedKeys.biome. That naming matters because assist sits close to Language Server Protocol semantics: an editor asks for code actions, Biome decides which actions apply, and the selected action returns edits. For useSortedPackageJson, the implementation evidence shows the edit logic is organized as deterministic JSON object transformations.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs

A useful mental model is to treat an assist action as a small, source-aware refactoring pass. The action first needs to determine whether the current syntax tree already matches the expected form. If no change is needed, it should avoid emitting an unnecessary diagnostic or edit. If a change is needed, it should produce a transformed value with the same semantic content but with a better organization. The sorter module documents that try_transform_field is the single source of truth for both checks: needs_transformation() tests whether it returns Some, and apply_field_transformer() unwraps that result to apply the edit.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs

System-to-Code Mapping

The useSortedPackageJson implementation is organized around field-specific transformers rather than a single generic object sort. The sorter module imports AnyJsonValue and JsonObjectValue, then dispatches on FieldTransformer. Simple variants call helpers such as alphabetical sorting or fixed key-order sorting for specific object shapes. Examples visible in the dispatch include people fields, URL fields, bugs fields, directories, Volta, binary entries, and Git hooks. That structure lets the action preserve package-manifest conventions where alphabetical order would be too blunt, while still using reusable object-ordering helpers for repeated patterns.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs

Several transformer variants delegate to specialized modules. The module declarations include dependencies, dependencies_meta, eslint_config, exports, prettier_config, and scripts, which reflects how much package metadata has domain-specific ordering behavior. Dependency maps often need package-name comparison, scripts may need lifecycle-aware ordering, and export maps have conventions that differ from plain object sorting. The public assist remains one action, but the repository decomposes it into focused sorters so each convention can evolve without turning the top-level dispatcher into a collection of ad hoc comparisons.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs

The pnpm configuration path illustrates the action’s nested behavior. The local sort_pnpm_config function first transforms the nested overrides property. When overrides is an object, the comparator extracts package names through dependencies_meta::get_package_name, which strips version specifier concerns before comparing keys. After that nested transformation, the function sorts the top-level pnpm keys with PNPM_BASE_CONFIG_PROPERTIES. It returns a transformed object if either the nested override ordering or the top-level key ordering changed, preserving the action’s rule that no edit is produced when the manifest is already organized.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs

Package Manifest Examples

Biome’s own npm package manifests show why a package-aware assist is more useful than a generic JSON sorter. The main @biomejs/biome package exposes a bin mapping for the biome executable, includes configuration_schema.json in its published files, declares web-toolchain keywords across JavaScript, TypeScript, JSON, CSS, GraphQL, and related formats, and depends optionally on platform-specific native CLI packages. That manifest combines human-readable metadata, package-manager metadata, distribution files, executable entry points, and platform selection details, all in one JSON object.

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

The backend package gives another concrete shape. @biomejs/backend-jsonrpc describes itself as bindings to the JSON-RPC Workspace API of the Biome daemon, has TypeScript build and test scripts, publishes dist/, and lists optional dependencies for every supported native CLI package. A package sort action must handle this kind of manifest without damaging intent: scripts should remain useful to maintainers, files should remain a publication contract, repository.directory should stay attached to the repository object, and dependency sections should be ordered in a way that makes reviews predictable.

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

The platform-specific CLI packages are intentionally small, but they reveal another important convention. @biomejs/cli-darwin-arm64 and @biomejs/cli-darwin-x64 constrain installation through os and cpu, while @biomejs/cli-linux-arm64-musl also includes libc: musl. These manifests are selected as optional dependencies from the main packages, so consistency matters across many nearly identical files. Sorting package fields according to conventions makes diffs easier to review when versions, repository directories, engine ranges, or platform selectors change across the native package matrix.

Sources: packages/@biomejs/cli-darwin-arm64/package.json, packages/@biomejs/cli-darwin-x64/package.json, packages/@biomejs/cli-linux-arm64-musl/package.json

Implementation Reference

The core repository-level contract visible for useSortedPackageJson is try_transform_field(value: &AnyJsonValue, transformer: FieldTransformer, root_object: &JsonObjectValue) -> Option<AnyJsonValue>. The input value is the field value being considered, the transformer tells the dispatcher which package-manifest convention applies, and the root object is available to transformations that need broader manifest context. The output is None when no transformation applies or the value is already sorted, and Some(AnyJsonValue) when the action can replace the field with an organized value.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs

The visible transformer cases provide a compact reference for contributor expectations. FieldTransformer::None performs no edit. SortObject sorts a JSON object alphabetically. SortPeopleObject, SortURLObject, SortBugsObject, SortDirectories, SortVolta, SortBinary, and SortGitHooks sort objects according to fixed field-order constants. SortDependencies, SortDependenciesMeta, SortScripts, SortExports, and the partially visible tool-configuration variants delegate to their modules. This separation is the extension point: new package-manifest conventions should usually become a targeted transformer or helper rather than being folded into unrelated sort behavior.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs

Developer Workflow and Next Steps

For users, the practical workflow is to enable assist, enable the desired source action, and let the editor or CLI apply the code action. In an editor, the official docs recommend source.fixAll.biome for applying Biome fixes on save and action-specific codes for targeted actions. For package manifests, the expected result is not a semantic package change; it is an organized package.json that follows the conventions encoded by Biome’s JSON analyzer. If applying the assist changes behavior, that should be treated as a bug because assist fixes are intended to be safe.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs

For contributors, start by reading the sorter dispatcher and the existing package manifests together. The dispatcher explains which object shapes get special treatment, while the manifests show the kinds of publication metadata Biome maintains in practice: executable entry points, native optional packages, scripts, repository directories, engines, and publication files. When changing or extending useSortedPackageJson, verify both decision paths described in the source comments: the transformation predicate and the edit application must continue to use the same transformation logic. Related pages to read next are configure-biome for assist configuration, editors-lsp-daemon for code-action delivery, and linter-overview-and-rules for the difference between rules and assist actions.

Sources: crates/biome_json_analyze/src/assist/source/use_sorted_package_json/sorters/mod.rs, packages/@biomejs/backend-jsonrpc/package.json, packages/@biomejs/biome/package.json