Biome 13 🧹 VS Code Extension — Format on save and diagnostics - KandZ

⏱️ Estimated read: 12 min | |

The Biome VS Code extension is the editor-side surface of the same toolchain that the CLI runs. It does not have its own formatting engine and its own lint rules; it starts a language server that is the Biome binary, and the server provides the formatting, the diagnostics, and the code actions through the Language Server Protocol . The extension is the client, and the Biome binary is the server. The distinction matters because the extension’s behavior is the server’s behavior, and the server is the version that the project has installed in its node_modules (or the global binary for the files outside a project).

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

The extension registers itself as a formatter for the supported file types, and it registers as a diagnostics provider and a code action provider. The registration is gated by the biome.enabled setting, and the default is true. When the setting is true and the workspace folder contains a biome.json, the extension activates for that folder . The activation is the mechanism that keeps the extension from interfering with the projects that do not use Biome.

Key point: The extension is a language server client. It registers as a formatter and a diagnostics provider when biome.enabled is true and the workspace has a biome.json. The format on save is the VS Code editor.formatOnSave setting, and the fix on save is the editor.codeActionsOnSave setting with the source.fixAll.biome action. The extension uses the project’s Biome binary, and the version must match the CLI’s version to keep the editor and the command line consistent.

Why the extension is the language server client

The single-engine problem. The extension does not reimplement the formatting and the linting. It spawns the Biome binary as a language server, and the server does the work. The server is the same binary that the biome check command runs, which means the editor and the CLI produce the same result for the same file and the same configuration . The single engine is the mechanism that keeps the two surfaces consistent.

The binary-resolution problem. The extension needs to find the Biome binary. It looks in the project’s node_modules first, and it falls back to the global installation for the files outside a project, such as the single files and the untitled files . The biome.lsp.bin setting is the override for the cases where the automatic resolution fails, such as the Alpine container where the musl binary is the one that works . The resolution is the mechanism that determines which Biome version the editor uses.

The multi-root problem. A VS Code workspace can contain the multiple project folders, and each folder can have its own biome.json and its own Biome version. The extension v3 added the multi-root support, and each workspace folder runs its own independent Biome instance . The independence is the mechanism that keeps the projects isolated, and the isolation is the reason the biome.projects setting was removed in the final release .

The configuration-reload problem. The extension reloads the Biome instance when the project’s Biome dependency changes and when the extension’s configuration changes . The reload is the mechanism that makes the new version and the new settings take effect without the editor restart, and the automatic reload is the reason the developer does not need to reload the window after the pnpm add of the new Biome version.

The unsaved-file problem. The extension supports the unsaved (untitled) files and the VS Code settings files. For those files, the extension spins up a global Biome instance on demand, and the global installation is the requirement . The on-demand instance is the mechanism that lets the developer format the scratch file without the project, and the global requirement is the reason the extension notifies when the binary is missing.

a. The format on save and the fix on save

The format on save is the VS Code setting, not the Biome setting. The editor.formatOnSave: true is the mechanism that runs the formatter on every save, and the Biome extension is the formatter when it is the default formatter for the file type. The editor.defaultFormatter: "biomejs.biome" is the setting that makes Biome the default, and the “Format Document With…” command is the manual way to set it .

// .vscode/settings.json — the format on save
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true
}

The editor.defaultFormatter is the mechanism that selects the extension for the format command. The editor.formatOnSave is the mechanism that runs the format on every save. The two settings are the VS Code settings, and the Biome extension respects them .

The fix on save is the second setting. The editor.codeActionsOnSave object with the source.fixAll.biome action is the mechanism that applies the safe fixes on save, and the source.organizeImports.biome action is the mechanism that sorts the imports on save .

// .vscode/settings.json — the fix on save
{
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

The "explicit" value is the VS Code 1.85+ setting that applies the action only when the developer explicitly saves the file, not on the autosave . The source.fixAll.biome applies only the safe fixes, and the unsafe fixes are not applied on save unless the rule’s fix is made safe in the configuration . The distinction is the mechanism that keeps the save action from changing the behavior unexpectedly.

The fix on save requires the extension to be the code action provider. The biome.enabled setting is the gate, and the biome.json in the workspace folder is the second requirement . The extension does not register the code action provider for the folders without the configuration, which is the mechanism that keeps the extension inactive in the unrelated workspaces.

b. The diagnostics and the code actions

The diagnostics are the lint errors and the formatting differences that the language server reports. The extension displays them in the Problems panel and the editor gutter, and the diagnostics update as the developer types or saves . The diagnostics are the same as the CLI’s, because the server is the same binary .

The code actions are the quick fixes for the diagnostics that have the safe fixes. The extension registers as the code action provider, and the “Quick Fix” command is the mechanism that applies the fix for the diagnostic under the cursor . The code actions include the rule fixes and the import organization, and the source.fixAll.biome is the bulk version of the same actions .

// The diagnostic display
// The Problems panel lists the diagnostics.
// The Quick Fix applies the safe fix for the diagnostic.

The biome.enabled setting is the master switch. When it is false, the extension does not register the formatter and the diagnostics provider, and the Biome features are inactive for the workspace . The switch is the mechanism that lets the developer disable the extension for a specific workspace without uninstalling it.

The biome.requireConfiguration setting is the second gate. When it is true, the extension registers only when the workspace folder has a biome.json, and the registration is the mechanism that keeps the extension from processing the projects that do not use Biome . The setting is the default, and the explicit false is the mechanism that lets the extension process the folders without the configuration.

Complete Example Session

// ============================================
// PART 1: THE EXTENSION INSTALLATION
// ============================================

// The extension is installed from the VS Code Marketplace.
// The ID is "biomejs.biome".
// The VSCodium and the Cursor use the Open VSX registry.

// ============================================
// PART 2: THE DEFAULT FORMATTER
// ============================================

// .vscode/settings.json
{
  "editor.defaultFormatter": "biomejs.biome"
}

// The Biome is the default formatter for the supported files.

// ============================================
// PART 3: THE FORMAT ON SAVE
// ============================================

// .vscode/settings.json
{
  "editor.formatOnSave": true
}

// The file is formatted on every save.

// ============================================
// PART 4: THE FIX ON SAVE
// ============================================

// .vscode/settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit"
  }
}

// The safe fixes are applied on save.

// ============================================
// PART 5: THE IMPORT ORGANIZATION ON SAVE
// ============================================

// .vscode/settings.json
{
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit"
  }
}

// The imports are sorted on save.

// ============================================
// PART 6: THE EXTENSION SETTINGS
// ============================================

// .vscode/settings.json
{
  "biome.enabled": true,
  "biome.requireConfiguration": true
}

// The extension is enabled.
// The extension activates only when the biome.json exists.

// ============================================
// PART 7: THE BINARY OVERRIDE
// ============================================

// .vscode/settings.json
{
  "biome.lsp.bin": "/frontend/node_modules/.pnpm/@biomejs+cli-linux-arm64-musl@2.3.11/node_modules/@biomejs/cli-linux-arm64-musl/biome"
}

// The override is for the cases where the automatic resolution fails.
// The Alpine container is the example.

// ============================================
// PART 8: THE DIAGNOSTICS
// ============================================

// The lint errors appear in the Problems panel.
// The formatting differences appear in the editor.
// The server is the same binary as the CLI.

// ============================================
// PART 9: THE QUICK FIX
// ============================================

// The developer selects the diagnostic.
// The Quick Fix button applies the safe fix.
// The code action is the same as the CLI's safe fix.

// ============================================
// PART 10: THE CHECKLIST
// ============================================

// [ ] The extension is installed.
// [ ] The editor.defaultFormatter is "biomejs.biome".
// [ ] The editor.formatOnSave is true.
// [ ] The editor.codeActionsOnSave has the source.fixAll.biome.
// [ ] The biome.enabled is true.
// [ ] The biome.requireConfiguration is true.
// [ ] The biome.lsp.bin is set if the automatic resolution fails.

The ten parts covered the extension installation, the default formatter, the format on save, the fix on save, the import organization on save, the extension settings, the binary override, the diagnostics, the quick fix, and the checklist. The through-line is that the extension is the client, and the server is the Biome binary.

Quick Reference

The VS Code settings

Setting	Purpose
`editor.defaultFormatter`	Set to `"biomejs.biome"`
`editor.formatOnSave`	Enable the format on save
`editor.codeActionsOnSave`	The `source.fixAll.biome` and the `source.organizeImports.biome`

The extension settings

Setting	Default	Purpose
`biome.enabled`	`true`	The master switch
`biome.requireConfiguration`	`true`	Activate only when the `biome.json` exists
`biome.lsp.bin`	—	The binary override

The code action values

Value	Behaviour
`"explicit"`	Apply on the explicit save
`"always"`	Apply on the autosave as well
`"never"`	Do not apply

Best Practices

✅ Do This:

// Use the explicit value for the save actions
{ "editor.codeActionsOnSave": { "source.fixAll.biome": "explicit" } } // ✅

// Set the Biome as the default formatter
{ "editor.defaultFormatter": "biomejs.biome" }                     // ✅

❌ Don’t Do This:

// Leave the Prettier as the default formatter
{ "editor.defaultFormatter": "esbenp.prettier-vscode" } // the conflict // ❌

// Use the always value for the unsafe fixes
// The unsafe fixes can change the behavior on the autosave.      // ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
The format on save does not work	The `editor.formatOnSave` is false	Set it to `true`
The extension is inactive	The `biome.json` is missing and `biome.requireConfiguration` is true	Add the `biome.json` or set the setting to `false`
The binary is not found	The automatic resolution fails in the container	Set the `biome.lsp.bin`
The fixes conflict with Prettier	Both the formatters are active	Remove the Prettier and set Biome as the default

Real-World Examples

1. The default formatter

{ "editor.defaultFormatter": "biomejs.biome" }

2. The format on save

{ "editor.formatOnSave": true }

3. The fix on save

{ "editor.codeActionsOnSave": { "source.fixAll.biome": "explicit" } }

4. The import organization

{ "editor.codeActionsOnSave": { "source.organizeImports.biome": "explicit" } }

5. The extension enable

{ "biome.enabled": true }

6. The configuration requirement

{ "biome.requireConfiguration": true }

7. The binary override

{ "biome.lsp.bin": "/path/to/biome" }

8. The quick fix

Select the diagnostic and click the Quick Fix button.

9. The diagnostics panel

The lint errors appear in the Problems panel.

10. The status indicator

Click the status indicator to open the Biome logs.

Visual

The Extension and the Server

┌──────────────────────────────────────────────────────────────┐
│  THE EXTENSION IS THE CLIENT                                 │
│                                                              │
│  VS Code                                                     │
│  ┌─────────────────────┐                                    │
│  │ The Biome extension │  The LSP client                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The Biome binary    │  The LSP server                    │
│  │ (node_modules)      │  The same as the CLI               │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The format and the  │  The same result as the CLI        │
│  │ diagnostics         │                                    │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

The Save Actions

┌──────────────────────────────────────────────────────────────┐
│  THE SAVE ACTIONS                                            │
│                                                              │
│  The developer saves                                         │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ editor.formatOnSave │  The format                        │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ source.fixAll.biome │  The safe fixes                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ source.organize     │  The import sorting                │
│  │ Imports.biome       │                                    │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

The Binary Resolution

┌──────────────────────────────────────────────────────────────┐
│  THE BINARY RESOLUTION                                       │
│                                                              │
│  The extension looks for the binary                          │
│         │                                                    │
│         ├──▶ The project's node_modules                      │
│         │                                                    │
│         └──▶ The global installation                         │
│                                                              │
│  The biome.lsp.bin overrides the automatic resolution.       │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
The extension	The official Biome VS Code extension
The client	The LSP client for the Biome binary
The format on save	The `editor.formatOnSave` setting
The fix on save	The `editor.codeActionsOnSave` with the `source.fixAll.biome`
The master switch	The `biome.enabled` setting
The configuration gate	The `biome.requireConfiguration` setting
The binary override	The `biome.lsp.bin` setting

Key takeaways:

The extension is the language server client. It spawns the Biome binary and uses the LSP to provide the formatting and the diagnostics. The server is the same binary as the CLI, so the editor and the command line produce the same result .
The format on save is the VS Code setting. The editor.formatOnSave: true is the mechanism, and the editor.defaultFormatter: "biomejs.biome" is the formatter selection .
The fix on save is the editor.codeActionsOnSave setting. The source.fixAll.biome applies the safe fixes, and the source.organizeImports.biome sorts the imports. The "explicit" value applies the action on the explicit save .
The extension is gated by the biome.enabled and the biome.requireConfiguration settings. The extension activates when the setting is true and the workspace has the biome.json .
The binary resolution can fail in the containers. The biome.lsp.bin is the override for the cases where the automatic resolution does not find the binary, such as the Alpine container .

Remember: The Biome VS Code extension is the editor client for the Biome language server. The server is the Biome binary, and the extension provides the formatting and the diagnostics through the LSP. The format on save is the VS Code setting, and the fix on save is the code action. The extension is gated by the biome.enabled and the biome.requireConfiguration, and the binary is resolved from the project or the global installation.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!