Getting Started and Installation

Purpose and Scope

This page gives a first path through installing Biome and running it in a project. Biome is distributed to JavaScript users as the @biomejs/biome package, whose package metadata describes it as a web toolchain for formatting, linting, and more. The same package exposes the executable name biome through its bin field, so package-manager commands such as npx @biomejs/biome check and local npm scripts ultimately resolve to that command entry point. The official guide recommends installing Biome as an exact development dependency, while still allowing standalone binary workflows for projects that do not otherwise need Node.js.

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

The important installation idea is that @biomejs/biome is a thin user-facing distribution package plus platform-specific binary packages. The main package declares optional dependencies for Windows, macOS, Linux, musl Linux, x64, and arm64 CLI builds, all pinned to the same published version. That layout lets normal package managers select the right binary dependency for the current platform without requiring users to choose a package manually. A platform package such as @biomejs/cli-darwin-arm64 then records its supported operating system and CPU constraints directly in package metadata.

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

Use this page for installation, first commands, and the distinction between the CLI package, the JSON-RPC daemon backend, and the JavaScript API. It is not a full rule reference or configuration reference. After you have Biome installed, the next practical step is to generate biome.json, run format, lint, or check, and then move to the formatter, linter, or configuration pages depending on the first workflow you want to automate.

Relevant Source Files

• packages/@biomejs/biome/package.json - Defines the public npm package name, version, biome binary entry, Node engine floor, bundled files, keywords, and optional platform CLI dependencies.
• packages/@biomejs/cli-darwin-arm64/package.json - Shows how a platform-specific binary package advertises darwin and arm64 constraints, mirroring the official manual installation platform matrix.
• packages/@biomejs/backend-jsonrpc/package.json - Defines the JSON-RPC backend package, its Node engine floor, description, scripts, and the same family of optional CLI binary dependencies used to reach the daemon.
• packages/@biomejs/backend-jsonrpc/src/index.ts - Exports the functions that create a workspace client connected to a remote Biome daemon through JSON-RPC.
• packages/@biomejs/js-api/src/index.ts - Exports the JavaScript API facade, the Distribution enum, Biome.create, and shared configuration and diagnostic types for WebAssembly clients.
• packages/@biomejs/plugin-api/index.js - Guards against installing or importing the plugin API package as a general user API and points users toward @biomejs/js-api instead.

Install the CLI Package

For most projects, install Biome as a development dependency and pin the exact version. The official guide shows the -D -E pattern for npm, pnpm, bun, and yarn so the repository gets a reproducible tool version. The published package metadata supports that recommendation: @biomejs/biome is versioned as the public package, exposes bin/biome, includes the configuration schema among published files, and declares node >=14.21.3 for package consumers. Those details make the package suitable for local project scripts and CI jobs that invoke the same binary.

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

npm i -D -E @biomejs/biome
pnpm add -D -E @biomejs/biome
bun add -D -E @biomejs/biome
deno add -D npm:@biomejs/biome
yarn add -D -E @biomejs/biome

After installation, prefer invoking the project-local binary through your package manager. That avoids relying on a globally installed version and keeps editor integrations, CI, and developer machines aligned. The package keyword list explicitly includes JavaScript, TypeScript, JSON, JSONC, JSX, TSX, CSS, and GraphQL, which is a useful reminder that the first install does not install separate formatter and linter packages per language. Biome ships as one toolchain package with a command family behind the biome executable.

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

The same package is also useful as a dependency of automation. Because the executable name is biome, a package script can call biome check --write, biome format --write, or biome lint --write after the dependency is installed. The official Getting Started sequence presents format for formatting, lint for linting and safe fixes, and check for the combined workflow that formats, lints, and organizes imports. In a new project, start with check when you want the broad toolchain behavior and use narrower commands when a pipeline stage should do only one job.

npx @biomejs/biome format --write
npx @biomejs/biome lint --write
npx @biomejs/biome check --write
npx @biomejs/biome check --write src

Generate Configuration and Run the First Check

Biome can run with zero configuration, but most teams eventually want a committed biome.json file. The official guide recommends biome init for generating that file. The repository evidence for the npm package shows that configuration_schema.json is part of the published files, which is important for editor and configuration tooling: the installable package carries both the binary entry and schema material needed by the broader user experience. Treat init as the transition from trial execution to a project-owned policy file.

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

npx @biomejs/biome init
pnpx @biomejs/biome init
bunx --bun @biomejs/biome init
deno run -A npm:@biomejs/biome init
yarn exec biome -- init

A practical first run is to initialize configuration, inspect the generated file, and then execute check without --write to see diagnostics before changing files. When you are comfortable with the results, add --write to apply formatter output, organize imports, and safe lint fixes where the command supports them. This two-step habit is especially useful when introducing Biome to an existing repository, because it separates understanding reported changes from applying them. The installed package already contains the command entry point, so no additional formatter-specific installation step is required.

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

npx @biomejs/biome check
npx @biomejs/biome check --write

For CI, install dependencies normally and call the local Biome command in a non-writing mode. The official docs distinguish usage commands from the installation step, and the package design supports that distinction by making the CLI a project dependency rather than a global prerequisite. A typical CI gate should fail when formatting or lint diagnostics are present, while local developer commands can use --write to apply changes. If you later split pipelines, map format, lint, and check to the amount of work each stage should own.

Manual and Platform-Specific Installation

Manual installation is for users who want the standalone CLI binary without making Biome the reason a project has package.json. The official manual installation guide lists platform identifiers such as darwin-arm64, darwin-x64, linux-x64, linux-arm64, and Windows variants. The npm package layout reflects the same platform model: @biomejs/biome has optional dependencies for each supported binary package, while an individual package such as @biomejs/cli-darwin-arm64 declares os: darwin and cpu: arm64. The package manager path and the manual binary path are therefore two ways of reaching the same platform-specific executable concept.

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

If your team uses Homebrew, Winget, Arch Linux packages, Docker images, or direct release downloads, follow the official manual installation channel for the operating system. The repository package metadata still helps explain what must match: CPU architecture, operating system, and Biome version. For example, macOS Apple Silicon corresponds to the darwin-arm64 family, and the package metadata for that build requires Node only when consumed through npm. A downloaded standalone binary does not need to be installed because your application uses Node; it only needs to be executable and available on the command path used by your scripts.

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

The version alignment matters. The main @biomejs/biome package and its optional CLI packages are shown at 2.5.1 in the supplied metadata, and the optional dependencies are pinned to that same version. That keeps the JavaScript wrapper package and the selected native binary in sync. When debugging an installation problem, verify the package manager did not skip optional dependencies for the current platform, verify that the selected package matches the operating system and CPU, and then run biome --version through the same invocation path your editor or CI will use.

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

Programmatic APIs and Daemon Connectivity

Most users begin with the CLI, but the repository also publishes programmatic packages for advanced integrations. @biomejs/backend-jsonrpc is described as bindings to the JSON-RPC Workspace API of the Biome daemon. Its source entry point exports createWorkspace, which obtains the command for the platform and returns null when the platform is not supported, and createWorkspaceWithBinary, which accepts a command path, opens a socket, initializes a JSON-RPC transport with client information, and wraps that transport as a workspace client. This is the daemon-oriented integration path rather than the normal Getting Started command path.

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

The JavaScript API package is a different integration surface. Its entry point exports common types, configuration and diagnostic type unions from the WebAssembly builds, and a Distribution enum with BUNDLER, NODE, and WEB values. Biome.create accepts a distribution option and dynamically imports @biomejs/wasm-bundler, @biomejs/wasm-nodejs, or @biomejs/wasm-web. Choose this API when an application needs an embedded WebAssembly-backed Biome client rather than a spawned CLI process or daemon workspace connection.

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

The plugin API package is intentionally not the general-purpose JavaScript API. Its entry point immediately throws an error explaining that the package is intended for Biome JS plugins and asks whether the caller meant @biomejs/js-api. That guard is useful for new users because the package names are easy to confuse. If you are writing scripts or app integrations, start with the CLI for process-level automation, @biomejs/js-api for WebAssembly embedding, and @biomejs/backend-jsonrpc only when you specifically need the daemon workspace protocol.

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

Compact Reference

The shortest successful path for a new repository is install, initialize, inspect, and then run a non-writing check before applying changes. After that, decide whether Biome should be invoked by developers through package scripts, by CI as a verification gate, by editors through their integration layer, or by custom tooling through a programmatic API. Each path still depends on the same core concepts established here: a versioned Biome distribution, a platform-appropriate executable, and commands that expose formatter, linter, and combined toolchain behavior.

Next Steps

Continue with Configure Biome when you are ready to tune biome.json, rule settings, formatter options, or assist behavior. Read CLI Reference when you need command-by-command behavior beyond init, format, lint, and check. Use Editors, LSP, and Daemon if your immediate task is editor setup or daemon troubleshooting. If you are evaluating output differences while adopting Biome in an existing codebase, move to Migrate, Upgrade, and Compare Formatting before applying broad writes to the repository.