From 9ffc06a0c6b919e9732484c0d6793c0ec29abcca Mon Sep 17 00:00:00 2001 From: Nicolas Hedger Date: Wed, 21 Aug 2024 21:21:19 +0200 Subject: [PATCH 01/12] wip --- src/content/docs/reference/vscode.mdx | 157 ++++++++------------------ 1 file changed, 48 insertions(+), 109 deletions(-) diff --git a/src/content/docs/reference/vscode.mdx b/src/content/docs/reference/vscode.mdx index d31bb946c..efab74e5a 100644 --- a/src/content/docs/reference/vscode.mdx +++ b/src/content/docs/reference/vscode.mdx @@ -1,140 +1,79 @@ --- -title: VSCode extension +title: VS Code extension description: Notes about the Biome's VSCode extension --- -# Biome VS Code Extension -[Biome](https://biomejs.dev/) unifies your development stack by combining the functionality of separate tools. It uses a single configuration file, has fantastic performance, and works with any stack. This extension brings Biome to your editor so that you can: +**Biome** ships with a first-party **VS Code extension** that provides the following +features. -- Format files *on save* or when issuing the *Format Document* command -- See lints while you type and apply code fixes -- Perform refactors +- Format on save +- Real-time code linting +- Code refactoring with quick fixes -## Installation +In this document, we'll go over how to install and configure the extension. -You can install the code extension by heading to the extension's [Visual Studio Code Market Place page](https://marketplace.visualstudio.com/items?itemName=biomejs.biome) or from within VS Code by either: +## Installing the extension -- Open the *extensions* tab (_View_ → _Extensions)_ and search for Biome. -- Open the _Quick Open Overlay_ (Ctrl/⌘+P or _Go -> Go to File_), enter `ext install biomejs.biome`, and hit enter. +The extension is available both on the +[VS Marketplace](https://marketplace.visualstudio.com/items?itemName=biomejs.biome) and the +[Open VSX registry](https://open-vsx.org/extension/biomejs/biome) and can be installed directly +by clicking one of the following links: -## Getting Started +[![](https://img.shields.io/badge/Install%20Biome-in%20VS%20Code-007ACC?style=flat&logo=biome)](vscode:extension/biomejs.biome) -### Default Formatter +[![](https://img.shields.io/badge/Install%20Biome-in%20VSCodium-007ACC?style=flat&logo=biome)](vscodium:extension/biomejs.biome) -Configure Biome as the default formatter for supported files to ensure that VS Code uses Biome over other formatters that you may have installed. You can do so by opening a JavaScript or TypeScript and then: +## Configuration reference -- Open the Command Palette (Ctrl/⌘+⇧+P or View → Command Palette) -- Select _Format Document With…_ -- Select _Configure Default Formatter…_ -- Select Biome +The following sections describe the configuration options available in the extension. -You can also enable Biome for specific languages only: +### `biome.enabled` -- [Open the `settings.json`](https://code.visualstudio.com/docs/getstarted/settings#_settingsjson): open the _Command Palette_(Ctrl/⌘+⇧+P) and select _Preferences: Open User Settings (JSON)_ -- And set the `editor.defaultFormatter` to `biomejs.biome` for the desired language +The `biome.enabled` setting controls whether the extension is enabled or not. By default, +the extension is enabled. -```json title="settings.json" -{ - "editor.defaultFormatter": "", - "[javascript]": { - "editor.defaultFormatter": "biomejs.biome" - } -} -``` - -This configuration sets Biome as the default formatter for JavaScript files. All other files will be formatted using `` - -## Configuration Resolution - -The extension automatically loads the `biome.json` file from the workspace’s root directory. - -## Biome Resolution - -The extension tries to use Biome from your project's local dependencies (`node_modules/@biomejs/biome`). We recommend adding Biome as a project dependency to ensure that NPM scripts and the extension use the same Biome version. +The `biome.enabled` setting controls whether the extension is enabled or not. By default, +the extension is enabled. This setting can be set at various levels, including globally, +workspace, and folder. -You can also explicitly specify the `Biome` binary the extension should use by configuring the `biome.lspBin` setting in your editor options. +VS Code's [setting precedence rules](https://code.visualstudio.com/docs/getstarted/settings#_settings-precedence) apply, +so if you set the `biome.enabled` setting to `false` at the workspace level, the extension +will be disabled for all folders in the workspace, but you can override this setting at the +folder level. -If the project has no dependency on Biome and no explicit path is configured, the extension uses the Biome version included in its bundle. +### `biome.requireConfigFile` -## Usage +The `biome.requireConfigFile` setting controls whether the extension requires a `biome.{json,jsonc}` +file to be present at the root of a project in order to enable the extension for that project. By default, +the extension does not require a configuration file to be present. -### Format document +If you always explicitly create a configuration, this setting can be handy to ensure that the extension +is only enabled for Biome projects, an not others. -To format an entire document, open the _Command Palette_ (Ctrl/⌘+⇧+P) and select _Format Document_. - -To format a text range, select the text you want to format, open the _Command Palette_ (Ctrl/⌘+⇧+P), and select _Format Selection_. - -### Format on save - -Biome respects VS Code's _Format on Save_ setting. To enable format on save, open the settings (_File_ -> _Preferences_ -> _Settings_), search for `editor.formatOnSave`, and enable the option. - -### Fix on save - -Biome respects VS Code's _Code Actions On Save_ setting. To enable fix on save, add +### `biome.lsp.bin` +The `biome.lsp.bin` setting allows you to specify the path to the `Biome` binary that the extension +should use to run the language server. By default, the extension will attempt to use the `biome` binary +provided by your dependencies. When this setting is set, the discovery mechanism will be bypassed and +the specified binary will be used instead. ```json title="settings.json" { - "editor.codeActionsOnSave": { - "quickfix.biome": "explicit" - } + "biome.lsp.bin": "path/to/biome" } ``` -in vscode `settings.json`. - -### Imports Sorting [Experimental] - -The Biome VS Code extension supports imports sorting through the "Organize Imports" code action. By default this action can be run using the ⇧+Alt+O keyboard shortcut, or is accessible through the _Command Palette_ (Ctrl/⌘+⇧+P) by selecting _Organize Imports_. - -You can add the following to your editor configuration if you want the action to run automatically on save instead of calling it manually: +This setting can also be specified as an object, allowing you to specify the path to the binary for +different platforms. The keys of the object should be a valid combo (`{platform}-{arch}`) of a platform and an architecture +identifier as defined by the Node.js [`process.platform`](https://nodejs.org/api/process.html#process_process_platform) +and [`process.arch`](https://nodejs.org/api/process.html#process_process_arch) values. The value of the object should be +the path to the binary for that platform and architecture. ```json title="settings.json" { - "editor.codeActionsOnSave":{ - "source.organizeImports.biome": "explicit" + "biome.lsp.bin": { + "linux-x64": "path/to/biome-linux", + "darwin-x64": "path/to/biome-darwin", + "win32-x64": "path/to/biome-win32.exe" } -} -``` - -## Extension Settings - -### `biome.lspBin` - -The `biome.lspBin` option overrides the Biome binary used by the extension. -The workspace folder is used as the base path if the path is relative. - -### `biome.rename` - -Enables Biome to handle renames in the workspace (experimental). - -## Versioning - -We follow the specs suggested by [the official documentation](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions): - -Odd minor versions are dedicated to pre-releases, e.g. `*.5.*` . -Even minor versions are dedicated to official releases, e.g. `*.6.*`. - - -## Troubleshooting - -### I installed `@biomejs/biome`, but the extension shows a warning saying that it could not resolve library - -The library `@biomejs/biome` specifies some optional dependencies that are installed based on your OS and architecture. - -It's possible though, that the extension can't resolve the binary when loading the extension. This is caused - probably - by your package manager. - -**To resolve the issue**, try to install the binary manually. The warning should show you the binary that belongs to your machine. - -**If you work in a team that use different OSs/architectures**, it's advised to install all the binaries: - -- `@biomejs/cli-darwin-arm64` -- `@biomejs/cli-darwin-x64` -- `@biomejs/cli-linux-arm64` -- `@biomejs/cli-linux-x64` -- `@biomejs/cli-win32-arm64` -- `@biomejs/cli-win32-x64` - -### My `biome.json` file is ignored in a multi-root workspace - -Currently, support for multi-root workspaces is limited, making `biome.json` files placed in individual root folders sometimes invisible to the extension. For now, you may need to set up an individual workspace for each folder that depends on Biome. You can track our progress on [this issue](https://github.com/biomejs/biome/issues/1573). +} \ No newline at end of file From 46b8c5b19c58d8ce8254ea488ff05a89fa328edf Mon Sep 17 00:00:00 2001 From: Nicolas Hedger Date: Sun, 1 Sep 2024 15:18:50 +0200 Subject: [PATCH 02/12] wip --- src/content/docs/reference/vscode.mdx | 126 ++++++++++++++++++-------- 1 file changed, 88 insertions(+), 38 deletions(-) diff --git a/src/content/docs/reference/vscode.mdx b/src/content/docs/reference/vscode.mdx index efab74e5a..8342840b2 100644 --- a/src/content/docs/reference/vscode.mdx +++ b/src/content/docs/reference/vscode.mdx @@ -23,57 +23,107 @@ by clicking one of the following links: [![](https://img.shields.io/badge/Install%20Biome-in%20VSCodium-007ACC?style=flat&logo=biome)](vscodium:extension/biomejs.biome) -## Configuration reference +## Projects -The following sections describe the configuration options available in the extension. +The Biome extension operates on so-called _projects_. A project is a directory in which the extension will spawn a dedicated +Biome LSP server. The extension will implicitly create a project for every workspace folder in workspace (unless disabled), but +you can explicitly define projects using the `biome.projects` setting. -### `biome.enabled` +Projects give you the flexibility to setup Biome pretty much however you want, while still benefiting from sane +defaults. -The `biome.enabled` setting controls whether the extension is enabled or not. By default, -the extension is enabled. +### Implicit projects -The `biome.enabled` setting controls whether the extension is enabled or not. By default, -the extension is enabled. This setting can be set at various levels, including globally, -workspace, and folder. +Whether you open VS Code in _single-root_ or _multi-root_ mode, the extension will implicitly create a +project for every workspace folder in the workspace, unless projects have been explicitly registered +for a given workspace folder. -VS Code's [setting precedence rules](https://code.visualstudio.com/docs/getstarted/settings#_settings-precedence) apply, -so if you set the `biome.enabled` setting to `false` at the workspace level, the extension -will be disabled for all folders in the workspace, but you can override this setting at the -folder level. +Given the following workspace configuration, the extension will create two independent projects. -### `biome.requireConfigFile` +import { FileTree } from '@astrojs/starlight/components'; -The `biome.requireConfigFile` setting controls whether the extension requires a `biome.{json,jsonc}` -file to be present at the root of a project in order to enable the extension for that project. By default, -the extension does not require a configuration file to be present. + +- projects + - project-a/ + - project-b/ +- foo.code-workspace + -If you always explicitly create a configuration, this setting can be handy to ensure that the extension -is only enabled for Biome projects, an not others. +```json file=foo.code-workspace +{ + "folders": [ + { + "name": "Project A", + "path": "projects/project-a" + }, + { + "name": "Project B", + "path": "projects/project-b" + } + ] +} +``` + +### Explicit projects + +Projects can be explicitly defined using the `biome.projects` setting. This setting should be an array of objects, +each of which defines a project. The following properties are supported: -### `biome.lsp.bin` +- `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_. -The `biome.lsp.bin` setting allows you to specify the path to the `Biome` binary that the extension -should use to run the language server. By default, the extension will attempt to use the `biome` binary -provided by your dependencies. When this setting is set, the discovery mechanism will be bypassed and -the specified binary will be used instead. +The following example shows how to explicitly define the two projects used in the previous section. -```json title="settings.json" +```json title="foo.code-workspace" { - "biome.lsp.bin": "path/to/biome" + "folders": [ + { + "path": "projects/project-a" + }, + { + "path": "projects/project-b" + } + ], + "settings": { + "biome.projects": [ + { + "name": "Project A", + "path": "." + }, + { + "name": "Project B", + "path": "." + } + ] + } } ``` -This setting can also be specified as an object, allowing you to specify the path to the binary for -different platforms. The keys of the object should be a valid combo (`{platform}-{arch}`) of a platform and an architecture -identifier as defined by the Node.js [`process.platform`](https://nodejs.org/api/process.html#process_process_platform) -and [`process.arch`](https://nodejs.org/api/process.html#process_process_arch) values. The value of the object should be -the path to the binary for that platform and architecture. - -```json title="settings.json" +Projects are not constrained to the root of the workspace folder. You can also create projects for +subfolders of a workspace folder. Here's an example illustrating a monorepo setup where we create +independent projects for each package. + + +- .vscode/ + - settings.json +- packages + - foo/ + - src/ + - biome.json + - bar/ + - src/ + - biome.json + + +```json title=".vscode/settings.json" { - "biome.lsp.bin": { - "linux-x64": "path/to/biome-linux", - "darwin-x64": "path/to/biome-darwin", - "win32-x64": "path/to/biome-win32.exe" - } -} \ No newline at end of file + "biome.projects": [ + { + "path": "packages/foo" + }, + { + "path": "packages/bar" + } + ] +} +``` From e0494e4297b6bbd7a0642a9f1305c94dd0d96784 Mon Sep 17 00:00:00 2001 From: Nicolas Hedger Date: Sat, 14 Sep 2024 09:36:50 +0200 Subject: [PATCH 03/12] wip --- src/content/docs/reference/vscode.mdx | 271 ++++++++++++++++++-------- 1 file changed, 192 insertions(+), 79 deletions(-) diff --git a/src/content/docs/reference/vscode.mdx b/src/content/docs/reference/vscode.mdx index 8342840b2..8283111d8 100644 --- a/src/content/docs/reference/vscode.mdx +++ b/src/content/docs/reference/vscode.mdx @@ -2,6 +2,10 @@ title: VS Code extension description: Notes about the Biome's VSCode extension --- +import { FileTree } from '@astrojs/starlight/components'; +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import { Badge } from '@astrojs/starlight/components'; + **Biome** ships with a first-party **VS Code extension** that provides the following features. @@ -15,7 +19,7 @@ In this document, we'll go over how to install and configure the extension. ## Installing the extension The extension is available both on the -[VS Marketplace](https://marketplace.visualstudio.com/items?itemName=biomejs.biome) and the +[Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=biomejs.biome) and the [Open VSX registry](https://open-vsx.org/extension/biomejs/biome) and can be installed directly by clicking one of the following links: @@ -26,104 +30,213 @@ 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. The extension will implicitly create a project for every workspace folder in workspace (unless disabled), but -you can explicitly define projects using the `biome.projects` setting. +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. -Projects give you the flexibility to setup Biome pretty much however you want, while still benefiting from sane -defaults. +### Defining projects -### Implicit projects +Projects can be defined in two places: -Whether you open VS Code in _single-root_ or _multi-root_ mode, the extension will implicitly create a -project for every workspace folder in the workspace, unless projects have been explicitly registered -for a given workspace folder. +- At the **workspace** level (`.code-workspace`) +- At the **workspace folder** level (`.vscode/settings.json`) -Given the following workspace configuration, the extension will create two independent projects. +:::note[Implicit projects] +The extension automatically creates a project at the root of every workspace folder that does not have explicitly defined projects. +::: -import { FileTree } from '@astrojs/starlight/components'; +#### Defining projects in a workspace - -- projects - - project-a/ - - project-b/ -- foo.code-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 has the following properties: -```json file=foo.code-workspace -{ - "folders": [ - { - "name": "Project A", - "path": "projects/project-a" - }, - { - "name": "Project B", - "path": "projects/project-b" - } - ] -} -``` +- `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](#biomeprojects) for more details. -### Explicit projects +#### Defining projects in a workspace folder -Projects can be explicitly defined using the `biome.projects` setting. This setting should be an array of objects, -each of which defines a project. The following properties are supported: +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 has 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_. -The following example shows how to explicitly define the two projects used in the previous section. +Please refer to the [`biome.projects` config reference](#biomeprojects) for more details. -```json title="foo.code-workspace" -{ - "folders": [ - { - "path": "projects/project-a" - }, - { - "path": "projects/project-b" - } - ], - "settings": { - "biome.projects": [ - { - "name": "Project A", - "path": "." - }, - { - "name": "Project B", - "path": "." - } - ] - } -} -``` +### Enabling and disabling + +The extension is always enabled because it needs to keep track of the state of the workspace, however the it provides two settings +to control whether Biome LSP sessions should be created for indidividual projects: -Projects are not constrained to the root of the workspace folder. You can also create projects for -subfolders of a workspace folder. Here's an example illustrating a monorepo setup where we create -independent projects for each package. +- The [`biome.enabled`](#biomeenabled) setting, which can be set globally and per-project. +- The [`biome.requireConfigFile`](#biomerequireconfigfile) setting, which can be set globally and per-project. + +#### Using the `biome.enabled` setting + +As mentioned above, the [`biome.enabled`](#biomeenabled) setting can be set globally and per-project. When setting it globally, it applies to all workspace folders, unless +they themselves 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`](#biomerequireconfigfile) setting can be set globally and per-project. When setting it globally, it applies to all workspace folders, unless +they themselves override the setting. This allows you to require the presence of a [Biome configuration file](/guides/configure-biome#configuration-file-structure) 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. -- .vscode/ - - settings.json -- packages - - foo/ - - src/ +- src/ + - 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](##defining-projects-in-a-workspace) using the [`biome.projects`](#biomeprojects) +setting. + + +- api/ (workspace folder) - biome.json - - bar/ - - src/ + - src/ + - main.ts +- app/ (workspace folder) - biome.json + - src/ + - main.ts +- my.code-workspace -```json title=".vscode/settings.json" -{ - "biome.projects": [ +### 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](#defining-projects-in-a-workspace-folder) using the [`biome.projects`](#biomeprojects) +setting. + + + + + - .vscode/ + - settings.json ← projects defined in here + - packages/ + - foo/ + - src/ + - main.ts + - biome.json + - bar/ + - src/ + - main.ts + - biome.json + + + + ```json { - "path": "packages/foo" - }, + "biome.projects": [ + { + "path": "packages/foo" + }, + { + "path": "packages/bar" + } + ] + } + ``` + + + +## Settings reference + +The following settings are available for the extension. + +:::note[Settings precedence] +All settings are resolved using VS Code's [settings precedence](https://code.visualstudio.com/docs/getstarted/settings#_settings-precedence) rules. +This means that the value of the setting at the most specific level will be used. This allows you to set a global setting, and override it for specific +workspace folders. +::: + +### `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: + + + + - `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. + + + + ```json { - "path": "packages/bar" + "biome.lsp.bin": "/path/to/biome" + } + ``` + + + + When using an object, the key is the platform identifier, constructed from the `-` value, and the value is the path to the binary. + ```json + { + "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` + +**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. From 0a1b703ffdeb8bc9b2f787c06b17ba954f81d5a6 Mon Sep 17 00:00:00 2001 From: Nicolas Hedger Date: Sat, 14 Sep 2024 10:04:11 +0200 Subject: [PATCH 04/12] wip --- src/content/docs/reference/vscode.mdx | 49 +++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/src/content/docs/reference/vscode.mdx b/src/content/docs/reference/vscode.mdx index 8283111d8..0fc9a53c8 100644 --- a/src/content/docs/reference/vscode.mdx +++ b/src/content/docs/reference/vscode.mdx @@ -155,6 +155,55 @@ setting. +## Features + +### Formatting + +The Biome extension registers itself as a formatter for [supported file types](/internals/language-support), and supports formatting a whole file, or a selection of code. + +Run either of the following commands from the [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_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`](vscode://settings/editor.formatOnSave) setting to `true`. + +### Code fixing + +The Biome extension registers itself as a code action provider for [supported file types](/internals/language-support), 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`](vscode://settings/editor.codeActionsOnSave) setting to include the following: + +```diff +{ + "editor.codeActionsOnSave": { ++ "quickfix.biome": "explicit" + } +} +``` + +### Import sorting + +The extension is able to sort imports on save for [supported file types](/internals/language-support). To enable this feature, set VS Code's [`editor.codeActionsOnSave`](vscode://settings/editor.codeActionsOnSave) setting to include the following: + +```diff +{ + "editor.codeActionsOnSave": { ++ "source.organizeImports.biome": "explicit" + } +} +``` + + + ## Settings reference The following settings are available for the extension. From e23c139b0bdad748ecfb1b7205652e93c94ed77d Mon Sep 17 00:00:00 2001 From: Nicolas Hedger Date: Sat, 14 Sep 2024 15:00:07 +0200 Subject: [PATCH 05/12] rename menu item --- astro.config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/astro.config.ts b/astro.config.ts index 7d9207231..548a31d71 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -272,7 +272,7 @@ export default defineConfig({ }, }, { - label: "VSCode extension", + label: "VS Code extension", link: "/reference/vscode", translations: { ja: "VSCode拡張機能", From 54d499518c545bb3290641e7cc0aab44a2256bd1 Mon Sep 17 00:00:00 2001 From: Nicolas Hedger Date: Sat, 14 Sep 2024 15:00:19 +0200 Subject: [PATCH 06/12] rename menu item --- astro.config.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/astro.config.ts b/astro.config.ts index 548a31d71..543230d96 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -275,9 +275,9 @@ export default defineConfig({ label: "VS Code extension", link: "/reference/vscode", translations: { - ja: "VSCode拡張機能", - "zh-CN": "VSCode 扩展", - "pt-BR": "Extensão do VSCode", + ja: "VS Code拡張機能", + "zh-CN": "VS Code 扩展", + "pt-BR": "Extensão do VS Code", }, }, { From b033d1346d1bdd9d2f095da34a44d77dae2844f8 Mon Sep 17 00:00:00 2001 From: Nicolas Hedger Date: Sun, 15 Sep 2024 10:20:57 +0200 Subject: [PATCH 07/12] wip --- src/content/docs/reference/vscode.mdx | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/content/docs/reference/vscode.mdx b/src/content/docs/reference/vscode.mdx index 0fc9a53c8..795ebf145 100644 --- a/src/content/docs/reference/vscode.mdx +++ b/src/content/docs/reference/vscode.mdx @@ -289,3 +289,22 @@ You may want to set this setting to `verbose` when you encounter issues with the **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](https://code.visualstudio.com/api/references/vscode-api#ExtensionContext.globalState) to keep track of its state between VS Code restarts. +It also uses VS Code's [global storage](https://code.visualstudio.com/api/references/vscode-api#ExtensionContext.globalStorageUri) 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](https://code.visualstudio.com/docs/getstarted/userinterface#_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`](#biomelsptrace_server) setting to `verbose`, +and re-running the action that caused the issue. The trace will be made available the [output](vscode://workbrench/panel) panel, under the `Biome LSP trace (xxx)` select option. \ No newline at end of file From 03cbf2167a42f11aed2c9860af234bae7585c145 Mon Sep 17 00:00:00 2001 From: Nicolas Hedger <649677+nhedger@users.noreply.github.com> Date: Wed, 25 Sep 2024 13:38:38 +0200 Subject: [PATCH 08/12] Update src/content/docs/reference/vscode.mdx Co-authored-by: Emanuele Stoppa --- src/content/docs/reference/vscode.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/reference/vscode.mdx b/src/content/docs/reference/vscode.mdx index 795ebf145..c1127ea3a 100644 --- a/src/content/docs/reference/vscode.mdx +++ b/src/content/docs/reference/vscode.mdx @@ -65,7 +65,7 @@ Please refer to the [`biome.projects` config reference](#biomeprojects) for more ### Enabling and disabling -The extension is always enabled because it needs to keep track of the state of the workspace, however the it provides two settings +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`](#biomeenabled) setting, which can be set globally and per-project. From 998dfaf41edb25643e22b5635b4ea58f37add0e3 Mon Sep 17 00:00:00 2001 From: Nicolas Hedger <649677+nhedger@users.noreply.github.com> Date: Wed, 25 Sep 2024 13:39:17 +0200 Subject: [PATCH 09/12] Update src/content/docs/reference/vscode.mdx Co-authored-by: Emanuele Stoppa --- src/content/docs/reference/vscode.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/reference/vscode.mdx b/src/content/docs/reference/vscode.mdx index c1127ea3a..66ae58311 100644 --- a/src/content/docs/reference/vscode.mdx +++ b/src/content/docs/reference/vscode.mdx @@ -73,8 +73,8 @@ to control whether Biome LSP sessions should be created for indidividual project #### Using the `biome.enabled` setting -As mentioned above, the [`biome.enabled`](#biomeenabled) setting can be set globally and per-project. When setting it globally, it applies to all workspace folders, unless -they themselves override the setting. This allows you to enable or disable the extension for all workspace folders, or selectively enable or disable it for +As mentioned above, the [`biome.enabled`](#biomeenabled) 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 From 22e32aa0ba46950a3376ff82f16973b05575b688 Mon Sep 17 00:00:00 2001 From: Nicolas Hedger <649677+nhedger@users.noreply.github.com> Date: Wed, 25 Sep 2024 13:39:33 +0200 Subject: [PATCH 10/12] Update src/content/docs/reference/vscode.mdx Co-authored-by: Emanuele Stoppa --- src/content/docs/reference/vscode.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/reference/vscode.mdx b/src/content/docs/reference/vscode.mdx index 66ae58311..8e34c7208 100644 --- a/src/content/docs/reference/vscode.mdx +++ b/src/content/docs/reference/vscode.mdx @@ -79,8 +79,8 @@ specific workspace folders. #### Using the `biome.requireConfigFile` setting -The [`biome.requireConfigFile`](#biomerequireconfigfile) setting can be set globally and per-project. When setting it globally, it applies to all workspace folders, unless -they themselves override the setting. This allows you to require the presence of a [Biome configuration file](/guides/configure-biome#configuration-file-structure) for a Biome project to be enabled. +The [`biome.requireConfigFile`](#biomerequireconfigfile) 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](/guides/configure-biome#configuration-file-structure) 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. From cc66547731e4b9a5943c167837e48b405d1bf0a7 Mon Sep 17 00:00:00 2001 From: Nicolas Hedger <649677+nhedger@users.noreply.github.com> Date: Wed, 25 Sep 2024 13:39:54 +0200 Subject: [PATCH 11/12] Update src/content/docs/reference/vscode.mdx Co-authored-by: Emanuele Stoppa --- src/content/docs/reference/vscode.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/reference/vscode.mdx b/src/content/docs/reference/vscode.mdx index 8e34c7208..163e97fcb 100644 --- a/src/content/docs/reference/vscode.mdx +++ b/src/content/docs/reference/vscode.mdx @@ -194,7 +194,7 @@ To enable fix on save, update VS Code's [`editor.codeActionsOnSave`](vscode://se The extension is able to sort imports on save for [supported file types](/internals/language-support). To enable this feature, set VS Code's [`editor.codeActionsOnSave`](vscode://settings/editor.codeActionsOnSave) setting to include the following: -```diff +```diff title="settings.json" { "editor.codeActionsOnSave": { + "source.organizeImports.biome": "explicit" From 1cd91529396f06c784f2d1a44049796617282370 Mon Sep 17 00:00:00 2001 From: Nicolas Hedger <649677+nhedger@users.noreply.github.com> Date: Wed, 25 Sep 2024 13:46:01 +0200 Subject: [PATCH 12/12] clarify --- src/content/docs/reference/vscode.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/reference/vscode.mdx b/src/content/docs/reference/vscode.mdx index 163e97fcb..47e18611a 100644 --- a/src/content/docs/reference/vscode.mdx +++ b/src/content/docs/reference/vscode.mdx @@ -47,7 +47,7 @@ The extension automatically creates a project at the root of every workspace fol #### 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 has the following properties: +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_. @@ -57,7 +57,7 @@ Please refer to the [`biome.projects` config reference](#biomeprojects) for more #### 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 has the following properties: +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_. @@ -307,4 +307,4 @@ Both can be cleared and reset by running the `Biome: Troubleshoot - Reset` comma ### 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`](#biomelsptrace_server) setting to `verbose`, -and re-running the action that caused the issue. The trace will be made available the [output](vscode://workbrench/panel) panel, under the `Biome LSP trace (xxx)` select option. \ No newline at end of file +and re-running the action that caused the issue. The trace will be made available the [output](vscode://workbrench/panel) panel, under the `Biome LSP trace (xxx)` select option.