OpenCode Formatting Tools
OpenCode will, after each file write or edit,automaticallyuse the formatting tool of the corresponding language to format it, ensuring that the generated code always conforms to your project's code style. The entire process is completed silently in the background without any manual operation.
How it works
When OpenCode writes or edits a file, it automatically performs formatting in the following steps:
- Detect the file extension of the written or edited file (e.g.
.ts、.py、.goetc.) - Match the extension against all enabled formatting tools
- Run the matched formatting command on that file
- Automatically write the formatting result back to the file
For example, if your projectpackage.jsoncontainsprettierdependency, OpenCode will automatically detect it and after each edit of.js、.ts、.csssuch files, it calls prettier for formatting, without any additional configuration.
Built-in formatting tools
OpenCode has built-in support for formatting tools covering mainstream languages and frameworks, divided into two categories:
- Enabled when the command is available: Simply install the corresponding command in the system, and OpenCode will automatically detect and use it
- Requires project configuration file or dependencies: The project needs to include a specific configuration file or dependency package
| Formatting tool | Supported file extensions | Enabling requirement |
|---|---|---|
air |
.R |
airCommand available |
biome |
.js .jsx .ts .tsx .html .css .md .json .yamland more |
The project contains abiome.jsonorbiome.jsoncconfiguration file |
cargofmt |
.rs |
cargo fmtCommand available |
clang-format |
.c .cpp .h .hpp .inoand more |
The project contains a.clang-formatconfiguration file |
cljfmt |
.clj .cljs .cljc .edn |
cljfmtCommand available |
dart |
.dart |
dartCommand available |
dfmt |
.d |
dfmtCommand available |
gleam |
.gleam |
gleamCommand available |
gofmt |
.go |
gofmtCommand available |
htmlbeautifier |
.erb .html.erb |
htmlbeautifierCommand available |
ktlint |
.kt .kts |
ktlintCommand available |
mix |
.ex .exs .eex .heex .leex .neex .sface |
mixCommand available |
nixfmt |
.nix |
nixfmtCommand available |
ocamlformat |
.ml .mli |
ocamlformatCommand available, and the project contains a.ocamlformatconfiguration file |
ormolu |
.hs |
ormoluCommand available |
oxfmt(Experimental) |
.js .jsx .ts .tsx |
package.jsonThe project containsoxfmtdependency, and the corresponding experimental environment variable flag is set |
pint |
.php |
composer.jsonThe project containslaravel/pintdependency |
prettier |
.js .jsx .ts .tsx .html .css .md .json .yamland more |
package.jsonThe project containsprettierdependency |
rubocop |
.rb .rake .gemspec .ru |
rubocopCommand available |
ruff |
.py .pyi |
ruffCommand available and the corresponding configuration exists |
rustfmt |
.rs |
rustfmtCommand available |
shfmt |
.sh .bash |
shfmtCommand available |
standardrb |
.rb .rake .gemspec .ru |
standardrbCommand available |
terraform |
.tf .tfvars |
terraformCommand available |
uv |
.py .pyi |
uvCommand available |
zig |
.zig .zon |
zigCommand available |
When multiple formatting tools support the same extension (e.g.
.rsis also supported bycargofmtandrustfmt,.rbis also supported byrubocopandstandardrb), OpenCode will automatically choose based on the tools installed in the project. If you need to specify explicitly, you can disable unwanted formatting tools using the configuration below.
Configuration file structure
Custom configuration for formatting tools is written under theopencode.jsonofformatterfield, with the key being the formatting tool name (consistent with the name in the built-in table) and the value being the configuration object for that tool:
Example
"$schema": "https://opencode.ai/config.json",
"formatter": {
// Formatting tool name: configuration object
"prettier": {
// Fill in prettier's configuration options here
}
}
}
Each formatting tool supports the following configuration options:
| Configuration option | Type | Description |
|---|---|---|
disabled |
boolean |
Set totrueto disable the formatting tool; the remaining configuration options will be ignored |
command |
string[] |
The command array for performing formatting. You can use the$FILEplaceholder in the command; at runtime, it will be replaced with the full path of the file to be formatted |
environment |
object |
Environment variables injected when running the formatting tool, in key-value pair form |
extensions |
string[] |
The list of file extensions processed by this formatting tool (including the., e.g.".ts"） |
Disabling formatting tools
1. Disable all formatting tools
If you do not want OpenCode to automatically format any files, you can setformatterdirectly tofalse：
Example
"$schema": "https://opencode.ai/config.json",
"formatter": false // Globally disables all formatting tools; no formatting will be performed after files are written
}
2. Disable a specific formatting tool
If you only need to disable one formatting tool, in the configuration object of the corresponding tool, setdisabledtotrue, and other formatting tools will not be affected:
Example
"$schema": "https://opencode.ai/config.json",
"formatter": {
"prettier": {
"disabled": true // Only disables prettier; other formatting tools (such as ruff, gofmt) still work normally
}
}
}
Custom formatting tools
Through thecommand、environmentandextensionsconfiguration option, you can override the default behavior of built-in formatting tools, or add formatting tools that are not yet built into OpenCode.
1. Override built-in formatting tool commands
For example, specify particular arguments for prettier and restrict it to only process specific extensions:
Example
"$schema": "https://opencode.ai/config.json",
"formatter": {
"prettier": {
"command": ["npx", "prettier", "--write", "$FILE"],
// $FILE in the command array is a placeholder; at runtime, it will be replaced with the full path of the file to be formatted
// For example, the actual execution is: npx prettier --write /your/project/src/index.ts
"environment": {
"NODE_ENV": "development" // Environment variables injected when running prettier
},
"extensions": [".js", ".ts", ".jsx", ".tsx"]
// Override default extensions: run prettier only on these four file types, and do not process .html, .css, etc.
}
}
}
2. Add custom formatting tools
If the formatting tool you use is not in the built-in list, you can add it by specifying any name. You only need to provide the launch command and the file extensions to be processed:
Example
"$schema": "https://opencode.ai/config.json",
"formatter": {
"custom-markdown-formatter": { // Custom name (you can name it anything as long as it does not conflict with built-in tools)
"command": ["deno", "fmt", "$FILE"],
// Use deno fmt to format files; $FILE will be replaced with the actual file path
"extensions": [".md"] // Run this formatting tool only on .md files
}
}
}
3. Configure multiple formatting tools simultaneously
Example
"$schema": "https://opencode.ai/config.json",
"formatter": {
"prettier": {
"command": ["npx", "prettier", "--write", "$FILE"],
"environment": {
"NODE_ENV": "development"
},
"extensions": [".js", ".ts", ".jsx", ".tsx"]
},
"ruff": {
"disabled": true // ruff is not used in the project, so disable it
},
"custom-markdown-formatter": {
"command": ["deno", "fmt", "$FILE"],
"extensions": [".md"]
}
}
}