VS Code extension

Biome ships with a first-party VS Code extension that provides the following features.

Format on save
Real-time code linting
Code refactoring with quick fixes

In this document, we’ll go over how to install and configure the extension.

Installing the extension

The extension is available both on the Visual Studio Marketplace and the Open VSX registry and can be installed directly by clicking one of the following links:

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, and to have different configurations for each project.

Defining projects

Projects can be defined in two places:

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

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 enabled 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.

It is a good idea to enable this setting globally when you know you always use a biome.json file, and you want to avoid the extension creating projects for workspace folders that don’t use Biome.

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 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 Biome projects are defined. In this case, you’ll need to explicitly define projects using the biome.projects setting.

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

{
  "biome.projects": [
    {
      "path": "packages/foo"
    },
    {
      "path": "packages/bar"
    }
  ]
}

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 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.

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:

{
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit"
  }
}

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:

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

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.
configFile (optional): The path to a custom configuration file to use for the project. This is useful if you want to rename the biome.json file, for example. By default, the LSP server will look for a biome.{json,jsonc} file in the root of the project directory.

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.
configFile (optional): The path to a custom configuration file to use for the project. This is useful if you want to rename the biome.json file, for example. By default, the LSP server will look for a biome.{json,jsonc} file in the root of the project directory.

`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

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

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.

{
  "biome.lsp.bin": {
    "darwin-arm64": "/path/to/biome",
    "win32-x64": "/path/to/biome.exe"
  }
}

`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.

`biome.experimental.rename` experimental

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

This experimental setting control whether Biome should be used to rename symbols when using the Rename Symbol command.

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.