VS Code extension

Biome comes with an official VS Code extension that tightly integrates with your code editor, providing formatting, linting, and code refactoring features to your development workflow.

This reference document provides an overview of the extension’s features, how to install it, and how to configure it for your projects.

Installing the extension

The recommended way to install the extension is through the Visual Studio Code Marketplace for VS Code users, or the Open VSX registry for VSCodium and other derivatives such as Cursor.

Projects

The Biome extension operates on so-called projects. A project is a directory in which the extension will spawn a dedicated Biome LSP server. This is useful because it allows you to use different versions of Biome for different projects, even if they are part of the same workspace folder.

Defining projects

Projects can be defined in two places:

At the workspace level (in a .code-workspace file)
At the workspace folder level (in a .vscode/settings.json file)

Defining projects in a workspace

To define projects in a workspace, add a settings.biome.projects property to the .code-workspace file. This setting accepts an array of project definitions, each of which must specify the following properties:

name: The name of the workspace folder that the project is associated with
path : The path to the project directory, relative to the root of the workspace folder.

Please refer to the biome.projects config reference for more details.

Defining projects in a workspace folder

To define projects in a workspace folder, add a biome.projects property to the .vscode/settings.json file. This setting accepts an array of project definitions, each of which must specify the following property:

path: The path to the project directory, relative to the root of the workspace folder.

Please refer to the biome.projects config reference for more details.

Enabling and disabling

The extension is always activated because it needs to keep track of the state of the workspace, however it provides two settings to control whether Biome LSP sessions should be created for indidividual projects:

The biome.enabled setting, which can be set globally and per-project.
The biome.requireConfigFile setting, which can be set globally and per-project.

Using the `biome.enabled` setting

As mentioned above, the biome.enabled setting can be set globally and per-project. When setting it globally, it applies to all workspace folders unless they override the setting. This allows you to enable or disable the extension for all workspace folders or selectively enable or disable it for specific workspace folders.

Using the `biome.requireConfigFile` setting

The biome.requireConfigFile setting can be set globally and per project. When setting it globally, it applies to all workspace folders unless they override the setting. This allows you to require the presence of a Biome configuration file for a Biome project to be enabled.

Common use cases

Single-root workspaces

A single-root workspace is your typical VS Code workspace, where there is only one workspace folder. Unless told otherwise, the extension will automatically create a project at the root of the workspace folder. This is the most common use case.

Directorysrc/
- main.ts
biome.json
package.json

Multi-root workspaces

A multi-root workspace is a workspace where there are multiple workspace folders. In this case, the extension will automatically create a project at the root of each workspace folder. You can also explicitly define projects using the biome.projects setting.

Directoryapi/ (workspace folder)
- biome.json
- Directorysrc/
  - main.ts
Directoryapp/ (workspace folder)
- biome.json
- Directorysrc/
  - main.ts
my.code-workspace

Monorepos

A monorepo is typically a workspace folder in which multiple projects are defined. Unless you have Biome installed at the root of the monorepo. you’ll want to explicitly define projects using the biome.projects to tell the extension where to look for Biome projects.

File structure
.vscode/settings.json

Directory.vscode/
- settings.json ← projects defined in here
Directorypackages/
- …
Directoryfoo/
- Directorysrc/
  - …
- main.ts
- biome.json
Directorybar/
- Directorysrc/
  - …
- main.ts
- biome.json

1
{
2
  "biome.projects": [
3
    {
4
      "path": "packages/foo"
5
    },
6
    {
7
      "path": "packages/bar"
8
    }
9
  ]
10
}

Features

Formatting

The Biome extension registers itself as a formatter for supported file types, and supports formatting a whole file, or a selection of code.

Run either one of the following commands from the command palette:

To format a whole file, run the Format Document command.
To format a selection of code, select the code and run the Format Selection command.

Formatting on save

To enable formatting on save, set VS Code’s editor.formatOnSave setting to true.

Code fixing

The Biome extension registers itself as a code action provider for supported file types, and provides code fixes for diagnostics that have safe fixes.

Manual quick fixes

To manually apply a quick fix, select the diagnostic and click the Quick Fix button.

Fix on save

To enable Fix on Save, update VS Code’s editor.codeActionsOnSave setting to include the following:

1
{
2
  "editor.codeActionsOnSave": {
3
    "source.fixAll.biome": "explicit"
4
  }
5
}

Import sorting

The extension is able to sort imports on save for supported file types. To enable this feature, set VS Code’s editor.codeActionsOnSave setting to include the following:

1
{
2
  "editor.codeActionsOnSave": {
3
    "source.organizeImports.biome": "explicit"
4
  }
5
}

Settings reference

The following settings are available for the extension.

`biome.enabled`

Default: true | Scopes: global, workspace, workspace folder

This setting controls whether projects will be created in a workspace or not. When set globally, it applies to all workspace folders, unless they themselves override the setting.

`biome.requireConfigFile`

Default: false | Scopes: global, workspace, workspace folder

This setting controls whether projects will be created depending on whether a Biome configuration file is present in the project directory. When set globally, it applies to all workspace folders, unless they themselves override the setting.

`biome.projects`

Default: undefined | Scopes: workspace, workspace folder

This setting allows you to define projects explicitly. It should be an array of project definitions, whose shape depends on the scope of the setting:

workspace folder
workspace

path (optional, defaults to .): The path to the project directory, relative to the root of the workspace folder. This is the path where the extension will spawn an independant Biome LSP server, and where you’d typically put your biome.json file.

name (required when defining at the workspace level): The name of the workspace folder that the project is associated with, which must match the name property of the workspace folder defined in the folders property.
path (optional, defaults to .): The path to the project directory, relative to the root of the workspace folder. This is the path where the extension will spawn an independant Biome LSP server, and where you’d typically put your biome.json file.

`biome.lsp.bin`

Default: undefined | Scopes: global, workspace, workspace folder

This setting allows you to override the path to the biome binary. This is useful if you want to use a different version of Biome, or if you want to use a binary that’s not on your PATH. In can be either a path to a binary, or an object that maps a platform to a path.

string
object

1
{
2
  "biome.lsp.bin": "/path/to/biome"
3
}

When using an object, the key is the platform identifier, constructed from the <process.os>-<process.arch> value, and the value is the path to the binary.

1
{
2
  "biome.lsp.bin": {
3
    "darwin-arm64": "/path/to/biome",
4
    "win32-x64": "/path/to/biome.exe"
5
  }
6
}

`biome.lsp.trace.server`

Default: off | Scopes: global

This setting allows to set the logging level of the Biome LSP trace. The possible values are off, messages, verbose. You may want to set this setting to verbose when you encounter issues with the extension, and you’d like to share the logs with us.

Troubleshooting

There may be times when you encounter unexpected issues with the extension. Here a a couple tip to help you troubleshoot the most common issues, and reset the extension’s state.

Resetting the extension

The extension uses VS Code’s global state to keep track of its state between VS Code restarts. It also uses VS Code’s global storage to keep temporary copies of the biome binaries that it uses.

Both can be cleared and reset by running the Biome: Troubleshoot - Reset command from the command palette , which will stop all active sessions, clear the global state and restart the extension.

Accessing the LSP trace

If you encounter issues with the extension, we may ask you to share the LSP trace with us. You can do so by setting the biome.lsp.trace.server setting to verbose, and re-running the action that caused the issue. The trace will be made available the output panel, under the Biome LSP trace (xxx) select option.

Migrating from the `2.x` extension

If you are migrating from the 2.x extension, we recommend you to completely restart your editor to ensure all previous LSP sessions are terminated.