aljaz/opencode
1
0
Fork 0
mirror of https://github.com/aljazceru/opencode.git synced 2025-12-28 13:14:28 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: edit new docs

Browse Source
This commit is contained in:
Jay V
2025-08-04 19:52:03 -04:00
parent 5bf7691ea6
commit 81412b6197
5 changed files with 145 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
packages/web/src/content/docs/docs/formatters.mdx
View File

@@ -1,19 +1,21 @@
---
title: Formatters
description: Code formatting with opencode
description: opencode uses language specific formatters.
---
opencode automatically formats code files after they are written or edited using language-specific formatters. This ensures consistent code style across your project without manual intervention.
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.
## Built-in Formatters
---
opencode comes with several built-in formatters for popular languages and frameworks:
## Built-in
| Formatter | Languages/Extensions | Requirements |
opencode comes with several built-in formatters for popular languages and frameworks. Below is a list of the formatters, supported file extensions, and commands or config options it needs.
| Formatter | Extensions | Requirements |
| -------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| gofmt | .go | `gofmt` command available |
| mix | .ex, .exs, .eex, .heex, .leex, .neex, .sface | `mix` command available |
| prettier | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://prettier.io/docs/en/index.html) | `prettier` dependency in package.json |
| prettier | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://prettier.io/docs/en/index.html) | `prettier` dependency in `package.json` |
| biome | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://biomejs.dev/) | `biome.json` config file |
| zig | .zig, .zon | `zig` command available |
| clang-format | .c, .cpp, .h, .hpp, .ino, and [more](https://clang.llvm.org/docs/ClangFormat.html) | `.clang-format` config file |
@@ -23,17 +25,51 @@ opencode comes with several built-in formatters for popular languages and framew
| standardrb | .rb, .rake, .gemspec, .ru | `standardrb` command available |
| htmlbeautifier | .erb, .html.erb | `htmlbeautifier` command available |
Formatters are automatically enabled when their requirements are met in your project environment.
So if your project has `prettier` in your `package.json`, opencode will automatically use it.
## Configuration
---
You can customize formatters through the `formatter` section in your `opencode.json` configuration file.
## How it works
### Disabling Formatters
When opencode writes or edits a file, it:
To disable a specific formatter, set its `disabled` property to `true`:
1. Checks the file extension against all enabled formatters.
2. Runs the appropriate formatter command on the file.
3. Applies the formatting changes automatically.
This process happens in the background, ensuring your code styles are maintained without any manual steps.
---
## Configure
You can customize formatters through the `formatter` section in your opencode config.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"formatter": { }
}
```
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 |
| `environment` | object | Environment variables to set when running the formatter |
| `extensions` | string[] | File extensions this formatter should handle |
Let's look at some examples.
---
### Disabling formatters
To disable a specific formatter, set `disabled` to `true`:
```json title="opencode.json" {5}
{
"$schema": "https://opencode.ai/config.json",
"formatter": {
@@ -44,11 +80,13 @@ To disable a specific formatter, set its `disabled` property to `true`:
}
```
### Custom Formatters
---
You can override the default formatters or add new ones by specifying the command, environment variables, and file extensions:
### Custom formatters
```json title="opencode.json"
You can override the built-in formatters or add new ones by specifying the command, environment variables, and file extensions:
```json title="opencode.json" {4-10}
{
"$schema": "https://opencode.ai/config.json",
"formatter": {
@@ -63,25 +101,4 @@ You can override the default formatters or add new ones by specifying the comman
}
```
The `$FILE` placeholder in the command will be replaced with the path to the file being formatted.
### Configuration Options
Each formatter configuration supports these properties:
| Property | Type | Description |
| ------------- | -------- | ------------------------------------------------------- |
| `disabled` | boolean | Set to `true` to disable the formatter |
| `command` | string[] | The command to run for formatting |
| `environment` | object | Environment variables to set when running the formatter |
| `extensions` | string[] | File extensions this formatter should handle |
## How It Works
When opencode writes or edits a file, 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
This process happens seamlessly in the background, ensuring your code maintains consistent formatting without requiring manual steps.
The **`$FILE` placeholder** in the command will be replaced with the path to the file being formatted.

80
packages/web/src/content/docs/docs/lsp.mdx
View File

@@ -1,15 +1,17 @@
---
title: LSP Servers
description: Language Server Protocol integration with opencode
description: opencode integrates with your LSP servers.
---
opencode integrates with Language Server Protocol (LSP) to enhance how the LLM interacts with your codebase. LSP servers provide intelligent code analysis and editing capabilities for different programming languages.
opencode integrates with your Language Server Protocol (LSP) to help the LLM interacts with your codebase. It uses diagnostics to provide feebdack to the LLM. And _go-to-definition_ and _find-references_ to help navigate your codebase.
## Built-in LSP Servers
---
## Built-in
opencode comes with several built-in LSP servers for popular languages:
| LSP Server | Languages/Extensions | Requirements |
| LSP Server | Extensions | Requirements |
| ---------- | -------------------------------------------- | ----------------------------------- |
| typescript | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts | `typescript` dependency in project |
| gopls | .go | `go` command available |
@@ -19,17 +21,49 @@ opencode comes with several built-in LSP servers for popular languages:
| zls | .zig, .zon | `zig` command available |
| csharp | .cs | `.NET SDK` installed |
LSP servers are automatically enabled when their requirements are met in your project environment.
LSP servers are automatically enabled when one of the above file extensions are detected and the requirements are met.
## Configuration
---
You can customize LSP servers through the `lsp` section in your `opencode.json` configuration file.
## How It Works
### Disabling LSP Servers
When opencode opens a file, it:
To disable a specific LSP server, set its configuration to `{ "disabled": true }`:
1. Checks the file extension against all enabled LSP servers.
2. Starts the appropriate LSP server if not already running.
---
## Configure
You can customize LSP servers through the `lsp` section in your opencode config.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"lsp": { }
}
```
Each LSP server supports the following:
| Property | Type | Description |
| ---------------- | -------- | ------------------------------------------------- |
| `disabled` | boolean | Set this to `true` to disable the LSP server |
| `command` | string[] | The command to start the LSP server |
| `extensions` | string[] | File extensions this LSP server should handle |
| `env` | object | Environment variables to set when starting server |
| `initialization` | object | Initialization options to send to the LSP server |
Let's look at some examples.
---
### Disabling LSP servers
To disable a specific LSP server, set `disabled` to `true`:
```json title="opencode.json" {5}
{
"$schema": "https://opencode.ai/config.json",
"lsp": {
@@ -40,11 +74,13 @@ To disable a specific LSP server, set its configuration to `{ "disabled": true }
}
```
### Custom LSP Servers
---
### Custom LSP servers
You can add custom LSP servers by specifying the command and file extensions:
```json title="opencode.json"
```json title="opencode.json" {4-7}
{
"$schema": "https://opencode.ai/config.json",
"lsp": {
@@ -55,25 +91,3 @@ You can add custom LSP servers by specifying the command and file extensions:
}
}
```
### Configuration Options
Each LSP server configuration supports these properties:
| Property | Type | Description |
| ---------------- | -------- | ------------------------------------------------- |
| `disabled` | boolean | Set to `true` to disable the LSP server |
| `command` | string[] | The command to start the LSP server |
| `extensions` | string[] | File extensions this LSP server should handle |
| `env` | object | Environment variables to set when starting server |
| `initialization` | object | Initialization options to send to the LSP server |
## How It Works
When opencode opens a file, it:
1. Checks the file extension against all enabled LSP servers
2. Starts the appropriate LSP server if not already running
3. Provides intelligent code analysis and editing capabilities
This integration allows the LLM to better understand your codebase through features like diagnostics, go-to-definition, and find-references.

4
packages/web/src/content/docs/docs/mcp-servers.mdx
View File

@@ -16,6 +16,8 @@ Once added, MCP tools are automatically available to the LLM alongside built-in
You can define MCP servers in your opencode config under `mcp`.
---
### Local
Add local MCP servers using `"type": "local"` within the MCP object. Multiple MCP servers can be added. The key string for each server can be any arbitrary name.
@@ -43,6 +45,8 @@ Add local MCP servers using `"type": "local"` within the MCP object. Multiple MC
You can also disable a server by setting `enabled` to `false`. This is useful if you want to temporarily disable a server without removing it from your config.
---
### Remote
Add remote MCP servers under `mcp` with `"type": "remote"`.

53
packages/web/src/content/docs/docs/plugins.mdx
View File

@@ -1,22 +1,31 @@
---
title: Plugins
description: Extend opencode with custom plugins.
description: Write your own plugins to extend opencode.
---
Plugins allow you to extend opencode's functionality by hooking into various events and customizing behavior. You can create plugins to add new features, integrate with external services, or modify opencode's default behavior.
Plugins allow you to extend opencode by hooking into various events and customizing behavior. You can create plugins to add new features, integrate with external services, or modify opencode's default behavior.
---
## Creating a Plugin
## Create a plugin
A plugin is a JavaScript/TypeScript module that exports one or more plugin
A plugin is a **JavaScript/TypeScript module** that exports one or more plugin
functions. Each function receives a context object and returns a hooks object.
They are loaded from the `.opencode/plugin` directory either in your proejct or
globally in `~/.config/opencode/plugin`.
### Basic Structure
---
```typescript title=".opencode/plugin/example.js"
### Location
Plugins are loaded from:
1. `.opencode/plugin` directory either in your proejct
2. Or, globally in `~/.config/opencode/plugin`
---
### Basic structure
```js title=".opencode/plugin/example.js"
export const MyPlugin = async ({ app, client, $ }) => {
console.log("Plugin initialized!")
@@ -28,15 +37,17 @@ export const MyPlugin = async ({ app, client, $ }) => {
The plugin function receives:
- `app` - The opencode application instance
- `client` - An opencode SDK client for interacting with the AI
- `$` - Bun's shell API for executing commands
- `app`: The opencode application instance.
- `client`: An opencode SDK client for interacting with the AI.
- `$`: Bun's [shell API](https://bun.com/docs/runtime/shell) for executing commands.
### TypeScript Support
---
### TypeScript support
For TypeScript plugins, you can import types from the plugin package:
```typescript title="my-plugin.ts"
```ts title="my-plugin.ts" {1}
import type { Plugin } from "@opencode-ai/plugin"
export const MyPlugin: Plugin = async ({ app, client, $ }) => {
@@ -50,11 +61,15 @@ export const MyPlugin: Plugin = async ({ app, client, $ }) => {
## Examples
### Notification Plugin
Here are some examples of plugins you can use to extend opencode.
---
### Send notifications
Send notifications when certain events occur:
```javascript title=".opencode/plugin/notification.js"
```js title=".opencode/plugin/notification.js"
export const NotificationPlugin = async ({ client, $ }) => {
return {
event: async ({ event }) => {
@@ -67,9 +82,13 @@ export const NotificationPlugin = async ({ client, $ }) => {
}
```
### .env Protection
Here `osascript` is a command that runs on macOS and sends notifications.
Integrate with external services:
---
### .env protection
Prevent opencode from reading `.env` files:
```javascript title=".opencode/plugin/slack.js"
export const EnvProtection = async ({ client, $ }) => {