docs: clarify LSP and formatter opt-in config (#25502)

2026-05-03 00:09:50 +00:00
parent 85bb9007ba
commit 6b68b1020e
5 changed files with 92 additions and 22 deletions
@@ -3,7 +3,7 @@ title: Formatters
 description: OpenCode uses language specific formatters.
 ---

-OpenCode automatically formats files after they are written or edited using language-specific formatters. This ensures that the code that is generated follows the code styles of your project.
+OpenCode can format files after they are written or edited using language-specific formatters. Formatters are disabled by default; enable them in your config before OpenCode will run them.

 ---

@@ -40,25 +40,36 @@ OpenCode comes with several built-in formatters for popular languages and framew
 | uv                   | .py, .pyi                                                                                                | `uv` command available                                                                                |
 | zig                  | .zig, .zon                                                                                               | `zig` command available                                                                               |

-So if your project has `prettier` in your `package.json`, OpenCode will automatically use it.
+When formatters are enabled, OpenCode will use `prettier` for matching files if your project has `prettier` in `package.json`.

 ---

 ## How it works

-When OpenCode writes or edits a file, it:
+When OpenCode writes or edits a file and formatters are enabled, it:

 1. Checks the file extension against all enabled formatters.
 2. Runs the appropriate formatter command on the file.
-3. Applies the formatting changes automatically.
+3. Applies the formatting changes.

-This process happens in the background, ensuring your code styles are maintained without any manual steps.
+This process happens in the background for enabled formatters.

 ---

 ## Configure

-You can customize formatters through the `formatter` section in your OpenCode config.
+You can enable and customize formatters through the `formatter` section in your OpenCode config.
+
+To enable all built-in formatters, set `formatter` to `true`.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "formatter": true
+}
+```
+
+Use an object to keep built-ins enabled while configuring overrides or custom formatters.

 ```json title="opencode.json"
 {
@@ -72,7 +83,7 @@ Each formatter configuration supports the following:
 | Property      | Type     | Description                                             |
 | ------------- | -------- | ------------------------------------------------------- |
 | `disabled`    | boolean  | Set this to `true` to disable the formatter             |
-| `command`     | string[] | The command to run for formatting                       |
+| `command`     | string[] | The command to run for formatting. Required for custom formatters; optional for built-ins. |
 | `environment` | object   | Environment variables to set when running the formatter |
 | `extensions`  | string[] | File extensions this formatter should handle            |

@@ -82,7 +93,7 @@ Let's look at some examples.

 ### Disabling formatters

-To disable **all** formatters globally, set `formatter` to `false`:
+If `formatter` is omitted, all formatters are disabled. To disable all formatters after another config enabled them, set `formatter` to `false`:

 ```json title="opencode.json" {3}
 {
@@ -108,7 +119,7 @@ To disable a **specific** formatter, set `disabled` to `true`:

 ### Custom formatters

-You can override the built-in formatters or add new ones by specifying the command, environment variables, and file extensions:
+You can configure built-in formatters with options like `environment` or `extensions`. To add a custom formatter, specify a `command` and `extensions`:

 ```json title="opencode.json" {4-14}
 {