How to Use Biome: The Beginner's Guide to One-Tool Formatting and Linting

CodexFuse Team · 2026-10-31T03:57:27.257Z · 14 min read

What is Biome, and why are beginners switching to it?

Biome is a single Rust-built toolchain that formats code, lints it, and organizes imports — replacing the ESLint plus Prettier pair with one binary and one configuration file. Learning how to use Biome takes about fifteen minutes, and most of that time is running three commands and skimming one config file.

Before this tool existed, a typical JavaScript project needed two parsers and two configuration files that constantly fought each other — developers usually added a compatibility package just to stop lint rules from conflicting with the formatter. Biome parses each file once and coordinates formatting, linting, and assist actions inside the same tool, so that whole category of conflict disappears (Flavio Copes, updated Sep 9, 2026).

Out of the box it handles JavaScript, TypeScript, JSX and TSX, JSON and JSONC, CSS, GraphQL, HTML, Vue, Svelte, and Astro — no extra packages needed for any of those languages (dev.to, retrieved Oct 30, 2026). The speed claims you will see everywhere — roughly 35x faster than Prettier in large codebases — come from community guides, not from CodexFuse measurements, and its linter ships with more than 500 rules drawn from ESLint, typescript-eslint, and other sources. Since version 2 it even does type-aware linting without requiring the TypeScript compiler.

How do I install Biome?

Install it as an exact development dependency with npm i -D -E @biomejs/biome. The -E flag pins the exact version — the official docs recommend it so the toolchain behaves identically on every machine, because formatter output can shift between versions.

Every major package manager works, and the command pattern is the same: pnpm add -D -E @biomejs/biome, yarn add -D -E @biomejs/biome, bun add -d -E @biomejs/biome, or the Deno equivalent. If your project file is a mess to begin with, our package.json generator builds a clean one before you add Biome to it.

There is also a standalone installer that does not require Node.js at all — handy for non-JavaScript projects or CI images without a Node runtime (biomejs.dev quick start, retrieved Oct 30, 2026). After installing, run npx biome version to confirm the binary answers. At the time of writing the current release is 2.6.4, the v2-era line this guide follows.

How do I create my first biome.json?

Run npx biome init in your project root — it writes a biome.json with the formatter, linter, and assist actions enabled on their recommended settings, plus a $schema reference so your editor can autocomplete and document every option. Biome actually works with no config file at all, but the config lets you share settings with your team and your editor.

Here is what the generator writes today (schema https://biomejs.dev/schemas/2.6.4/schema.json, verified against the official docs on Oct 30, 2026):

{
  "$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
  "vcs": { "enabled": false, "clientKind": "git", "useIgnoreFile": false },
  "files": { "ignoreUnknown": false },
  "formatter": { "enabled": true, "indentStyle": "tab" },
  "linter": { "enabled": true, "rules": { "preset": "recommended" } },
  "javascript": { "formatter": { "quoteStyle": "double" } },
  "assist": { "enabled": true, "actions": { "source": { "organizeImports": "on" } } }
}

Three things to notice as a beginner: the defaults use tabs and double quotes, the linter runs the recommended rule preset, and import organization is already switched on. If you want comments inside the config, run npx biome init --jsonc instead to generate a biome.jsonc file. A small honest hand-written config for a team project might look like this:

{
  "$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
  "formatter": { "indentStyle": "space", "indentWidth": 2 },
  "linter": { "enabled": true, "rules": { "preset": "recommended" } },
  "javascript": { "formatter": { "quoteStyle": "single" } },
  "assist": { "enabled": true, "actions": { "source": { "organizeImports": "on" } } }
}

Never copy a schema URL from an old blog post into a new project — 1.6 and 1.9 URLs are still floating around in 1.x-era guides, and the schema must match your installed major version or the editor will validate against the wrong options.

What do biome check, biome format, and biome lint actually do?

biome check runs all three jobs — the formatter, the linter, and assist actions like organizing imports — in a single pass. biome format and biome lint run one job at a time when you want to separate concerns. This is the command map most beginners need:

The crucial discipline beginners must learn: --write applies only safe fixes by default. Any diagnostics that remain after a --write pass either have no fix or have an unsafe one — they need your eyes, not a flag. There is an --unsafe flag, but the rule is simple: never run it by default; review the diff first (Flavio Copes, updated Sep 9, 2026).

One more command worth knowing early: npx biome explain noUnusedVariables prints the documentation for any rule, including its category (for example lint/correctness/noUnusedVariables) — use that category when you configure or suppress the rule (dev.to, retrieved Oct 30, 2026).

How do I set up Biome in VS Code?

Install the official Biome extension from the Visual Studio Marketplace — or from the Open VSX registry if you use VSCodium or Cursor — then open any supported file and go to Command Palette, "Format Document With…", "Configure Default Formatter", and choose Biome. The extension ships Biome's language server, so you get the same diagnostics, formatting, and assist actions as the CLI while you type or save.

After selecting Biome as the default formatter, open the extension reference to enable format and fix on save — that one toggle turns the editor into a live Biome pipeline. If you are new to the editor itself, our VS Code beginner guide walks through the setup the extension lives in.

Other editors are covered too: the Biome team maintains first-party extensions for Zed and IntelliJ, Helix connects to Biome's language server directly through the biome lsp-proxy command, and community extensions exist for Neovim (nvim-lspconfig, ALE, coc-biome), Vim (ALE), Sublime Text (LSP-biome), Emacs (lsp-mode), and Nova (biomejs.dev editor guide, retrieved Oct 30, 2026).

How do I add Biome to CI and pre-commit hooks?

For continuous integration, run biome ci — it checks formatting, linting, and assist actions and returns a non-zero exit code when anything fails, which fails the pipeline step. Pair it with a package.json script so the team runs the same check locally:

{
  "scripts": {
    "check": "biome check ./src",
    "check:fix": "biome check --write ./src",
    "ci": "biome ci ./src"
  }
}

For pre-commit hooks, the standard pairing is Husky plus lint-staged: lint-staged runs Biome only on staged files, with a config like "*.{js,ts,jsx,tsx,json,css}": "biome check --write --no-errors-on-unmatched" — the last flag keeps the hook from failing when a commit contains no matching files (dev.to, retrieved Oct 30, 2026).

A minimal GitHub Actions step looks like this — install, then check:

- name: Check with Biome
  run: |
    npm ci
    npx @biomejs/biome ci ./src

Keep the CI command read-only (biome ci, not --write): the pipeline's job is to verify, not to silently rewrite code. If you are setting up repositories for the first time, our GitHub beginner guide covers the repository and Actions basics this step assumes.

Biome vs ESLint: should I switch?

Switch if you want one zero-config tool that handles formatting and linting together; stay on ESLint if your project depends on plugin rules or specific configurations Biome does not cover. That is the honest dividing line, and the Biome team is upfront about it.

Biome's linter organizes rules into groups by purpose — suspicious, correctness, style, complexity, and others — with more than 500 rules drawn from ESLint and typescript-eslint lineage. But its rule ecosystem is still smaller than ESLint's, and there is no plugin system: if you rely on a niche plugin rule (framework-specific accessibility checks, company-internal rules), Biome cannot run it today.

The good news for existing projects is the migration path: biome migrate eslint --write ports rules, globals, overrides, and ignore patterns from both legacy and flat ESLint configurations, follows extends, loads shared and plugin configurations, and migrates .eslintignore. By default it migrates only rules identical to their ESLint source; pass --include-inspired to also migrate inspired rules — then review the result, because inspired rules deliberately differ in some options (biomejs.dev migration guide, retrieved Oct 30, 2026).

Biome vs Prettier: should I switch?

Switch if you want Prettier-style formatting inside the same binary that lints your code — community guides claim about 97% compatibility with Prettier output. But expect a one-time formatting diff: Biome stays close to Prettier without being byte-for-byte identical in every case, so the first biome check --write on a Prettier-formatted codebase will touch many lines.

biome migrate prettier --write ports your Prettier options and .prettierignore patterns, writing every option explicitly into biome.json to keep your current output as close as possible — differences that remain are documented on the official output-and-compatibility page. The practical advice from Flavio Copes (updated Sep 9, 2026): run the migration on a clean branch, review the formatting diff, and merge it as its own commit so it never pollutes a feature diff.

One philosophical difference matters: Biome's formatter is opinionated by design. Prettier lets you tweak more; Biome deliberately offers fewer knobs so teams stop debating style. If your team has strong formatting opinions Prettier currently satisfies, audit the option list before committing to the switch.

How do I migrate an existing ESLint and Prettier project to Biome?

Run this sequence on a clean branch, in order — install, migrate each old tool, verify, then remove the old dependencies:

1. Install Biome as an exact dev dependency: npm i -D -E @biomejs/biome, then npx biome init to create the starting biome.json.
2. Migrate the ESLint config: npx biome migrate eslint --write (add --include-inspired if you want inspired rules too). The command replaces the linter settings in your biome.json and sets the rule preset to none with only migrated rules enabled.
3. Migrate the Prettier config: npx biome migrate prettier --write. It ports options and ignore patterns, writing every option explicitly.
4. Review the result before relying on it — the official docs repeat this warning for every migration command. Check the diff, then run npx biome check --write and fix what remains.
5. Enable VCS integration so Biome reuses your .gitignore the way ESLint and Prettier did by default: set vcs.enabled to true in biome.json.
6. Remove the old tools — uninstall ESLint, Prettier, Stylelint, and their plugins — and replace their editor extensions with Biome's (biomejs.dev migration guide, retrieved Oct 30, 2026).

If a migration fails on plugin configs with cyclic references, the official troubleshooting path is: comment out the plugins and shared configs, run the migration, then restore them one at a time to find the culprit — and configure the unmigrated plugin rules by hand in biome.json afterwards.

What are Biome's honest limits?

Biome is opinionated, its rule ecosystem is smaller than ESLint's, and it has no plugin system — those are the three limits that actually decide migrations. If any of them is a dealbreaker for your project, keep the old tool for that job instead of forcing the switch.

The opinionated formatter means fewer style options than Prettier; teams that customized Prettier heavily may find Biome's defaults non-negotiable in places. The smaller rule set means framework-specific or company-specific rules may have no equivalent. And without plugins, there is no escape hatch for rules the core team has not implemented.

None of this makes Biome a bad choice for beginners — quite the opposite. Fewer knobs and one config file are exactly why a beginner can go from zero to a working formatter-plus-linter in fifteen minutes. Just make the decision with the limits in view, not as a surprise three months later.

Sources

• Biome official docs, "Quick start" (biomejs.dev, retrieved Oct 30, 2026) — install commands for every package manager plus the standalone installer, biome init, the generated biome.json (schema 2.6.4), and the check / check --write safe-fix discipline.
• Biome official docs, "Migrate from other tools" (biomejs.dev, retrieved Oct 30, 2026) — migrate eslint, migrate prettier, and migrate stylelint commands, identical vs inspired rules, the --include-inspired flag, and the VCS-integration step.
• Biome official docs, "Set up your editor" (biomejs.dev, retrieved Oct 30, 2026) — official VS Code, Zed, and IntelliJ extensions, Helix via biome lsp-proxy, and community extensions for Neovim, Vim, Sublime Text, Emacs, and Nova.
• Flavio Copes, "Biome: one tool for linting and formatting" (flaviocopes.com, updated Sep 9, 2026, retrieved Oct 30, 2026) — formatter/linter/assist breakdown, single-parse coordination, check vs format vs lint, safe vs unsafe fixes, the starter biome.json, and the expect-a-formatting-diff migration warning.
• dev.to (sina_devs), "Biome: a blazing-fast formatter with high Prettier compatibility" (retrieved Oct 30, 2026) — Rust toolchain, 500+ lint rules, type-aware linting in v2+ without the TypeScript compiler, language support list, install and VS Code/Zed setup.
• dev.to (vishdevwork), "Biome: Replace ESLint + Prettier With One Tool" (retrieved Oct 30, 2026) — the ~35x faster than Prettier speed claim, install and init commands, biome explain, and editor extensions.
• dev.to (recca0120), "Replace ESLint + Prettier with Biome: 35x Faster, One Tool" (retrieved Oct 30, 2026) — the 97% Prettier-compatibility claim, 455-rule linter coverage, and biome ci for CI pipelines.
• dev.to, "Best Code Linters and Formatters in 2026: The Practical Guide" (retrieved Oct 30, 2026) — pre-commit hooks with Husky and lint-staged, biome check --write --no-errors-on-unmatched.

Frequently asked questions

I'm a total beginner — is Biome hard to learn?

No. If you can run three terminal commands, you can use Biome: install it, run biome init, and run biome check --write. There is one config file, one binary, and no plugin setup — which is exactly why it is friendlier to beginners than assembling ESLint plus Prettier from scratch.

Is Biome free?

Yes. Biome is open-source and free to use in personal and commercial projects, and the official editor extensions cost nothing. The only thing you might pay for is whatever CI minutes your provider charges, the same as any other check.

Does Biome fully replace ESLint and Prettier?

For most JavaScript and TypeScript projects, yes — one tool covers formatting, linting, and import organization. The exceptions are projects that depend on ESLint plugins or rules Biome has not implemented, and teams whose Prettier customizations Biome's opinionated formatter cannot reproduce. Audit those two things before migrating.

What is the difference between safe and unsafe fixes?

A safe fix is a code change Biome can prove preserves behavior — removing an unused variable, for example. An unsafe fix might change what the code does, so Biome never applies it without the explicit --unsafe flag. The beginner rule: use --write freely, use --unsafe never by default, and always review the diff.

Will Biome change how my code looks compared to Prettier?

Slightly, the first time. Biome aims for high Prettier compatibility (community guides claim around 97%), but the output is not byte-for-byte identical, so expect a one-time formatting diff when you migrate. Run it as its own commit on a clean branch so the diff stays reviewable.