oxc/crates/oxc_language_server

oxc_language_server

This crate provides an LSP Server which is used inside an editor or IDE.

Server Capabilities

• Text Document Synchronization: FULL,
• Workspace
  • Workspace Folders: true
  • File Operations: false

For oxlint

• Workspace commands
  • oxc.fixAll, requires { uri: URL } as command argument. Does safe fixes in uri file.
• Code Actions Provider:
  • quickfix
  • source.fixAll.oxc, behaves the same as quickfix only used when the CodeActionContext#only contains source.fixAll.oxc.
• Diagnostic Provider
  • Only when Diagnostics Refresh is supported by your client

For oxfmt

• DocumentFormattingProvider

Workspace Options

These options can be passed with initialize, workspace/didChangeConfiguration and workspace/configuration.

Option Key	Value(s)	Default	Description
configPath	<string> | null	null	Path to a oxlint configuration file, passing a string will disable nested configuration. An empty string is treated as null
tsConfigPath	<string> | null	null	Path to a TypeScript configuration file. If your tsconfig.json is not at the root, alias paths will not be resolve correctly for the import plugin. An empty string is treated as null
unusedDisableDirectives	"allow" | "warn" | "deny"`	"allow"	Define how directive comments like // oxlint-disable-line should be reported, when no errors would have been reported on that line anyway
typeAware	<boolean> | null	null	Enables type-aware linting. When unset (null), uses the root config's options.typeAware value.
disableNestedConfig	false | true	false	Disabled nested configuration and searches only for configPath. Always disabled in Vite+ mode.
fixKind	fixKind values	safe_fix_or_suggestion	The level of a possible fix for a diagnostic, will be applied for the complete workspace (diagnostic, code action, commands and more).
rulesCustomization	Map<string, RulesCustomization>	<empty>	Rules customization, overriding severity or autofix with source.fixAll.oxc. The map key is the rule name, example: typescript/no-unused-vars
fmt.configPath	<string> | null	null	Path to a oxfmt configuration file, passing a string will disable nested configuration. When null or an empty string is passed, the server will use .oxfmtrc.json and the workspace root
fmt.disableNestedConfig	false | true	false	Disabled nested configuration and searches only for fmt.configPath. Always disabled in Vite+ mode.
Diagnostic Push Mode
run	"onSave" | "onType"	"onType"	Should the server lint the files when the user is typing or saving. Only applies to push mode clients; pull mode clients request diagnostics themselves.
Deprecated
fmt.experimental	true | false	false	(deprecated) Enables experimental formatting with oxc_formatter
flags	Map<string, string>	<empty>	(deprecated) Custom flags passed to the language server.

fixKind values:

• "safe_fix"
• "safe_fix_or_suggestion" (default)
• "dangerous_fix"
• "dangerous_fix_or_suggestion"
• "none"
• "all"

RulesCustomization struct:

interface RulesCustomization {
  // overriding the rule severity, when "off", the rule will not output diagnostics.
  severity?: "off" | "warn" | "error" | "hint" | "info";

  // allows to disable the autofix for a specific rule, even when the rule has a fix and the workspace `fixKind` allows it.
  // the user code action `quickfix` will still be available, but the `source.fixAll.oxc` & `source.fixAllDangerous.oxc` will ignore the rule.
  autofix?: boolean;
}

Diagnostics Modes

Depending on the client, the server will push diagnostics, or will wait for a pull request from the client. The server will prefer pull diagnostics when the client supports it and is also supporting workspace/diagnostic/refresh.

Supported LSP Specifications from Server

initialize

Returns the Server Capabilities.
The client can pass the workspace options like following:

{
  "initializationOptions": [
    {
      "workspaceUri": "file://workspace-directory",
      "options": {
        "run": "onType",
        "configPath": null,
        "tsConfigPath": null,
        "unusedDisableDirectives": "allow",
        "typeAware": false,
        "disableNestedConfig": false,
        "fixKind": "safe_fix",
        "rulesCustomization": {},
        "fmt.configPath": null,
        "fmt.disableNestedConfig": false,
        }
      }
    }
  ]
}

Flags (deprecated)

• key: disable_nested_config: Disabled nested configuration and searches only for configPath
• key: fix_kind: see FixKind values for possible values

initialized

When the client did not pass the workspace configuration in initialize, the server will request the configuration for every workspace with workspace/configuration. The server will tell the client with client/registerCapability to watch for .oxlintrc.json files or a custom oxc.configPath.

shutdown

The server will reset the diagnostics for all open files and send one or more textDocument/publishDiagnostics requests to the client.

Workspace

workspace/didChangeConfiguration

The client can pass the workspace options like following:

{
  "settings": [
    {
      "workspaceUri": "file://workspace-directory",
      "options": {
        "run": "onType",
        "configPath": null,
        "tsConfigPath": null,
        "unusedDisableDirectives": "allow",
        "typeAware": false,
        "disableNestedConfig": false,
        "fixKind": "safe_fix",
        "rulesCustomization": {},
        "fmt.configPath": null,
        "fmt.disableNestedConfig": false
      }
    }
  ]
}

When the client does not pass workspace options, the server will request them with workspace/configuration. The server will revalidate or reset the diagnostics for all open files and send one or more textDocument/publishDiagnostics requests to the client.

When changing the oxc.configPath settings: The server will tell clients with client/registerCapability to watch for .oxlintrc.json files or a custom oxc.configPath. The server will tell clients with client/unregisterCapability to stop watching for .oxlintrc.json files or a custom oxc.configPath.

workspace/didChangeWatchedFiles

The server expects this request when one oxlint configuration is changed, added or deleted. When the server is using Push Mode, the server will revalidate the diagnostics for all open files and send one or more textDocument/publishDiagnostics requests to the client. When the server is using Pull Mode, the server will tell the client to revalidate all diagnostics with workspace/diagnostic/refresh.

workspace/didChangeWorkspaceFolders

The server expects this request when adding or removing workspace folders. The server will request the specific workspace configuration, if the client supports it. The server will tell clients with client/registerCapability to watch for .oxlintrc.json files or a custom oxc.configPath. The server will tell clients with client/unregisterCapability to stop watching for .oxlintrc.json files or a custom oxc.configPath. When the server is using Push Mode, the server will revalidate the diagnostics for all open files and send one or more textDocument/publishDiagnostics requests to the client. When the server is using Pull Mode, the server will tell the client to revalidate all diagnostics with workspace/diagnostic/refresh.

workspace/executeCommand

Executes a Command if it exists. See Server Capabilities

TextDocument

textDocument/didOpen

The server will cache the internal content of the text document. When the server is using Push Mode, the server will validate the text document and send a textDocument/publishDiagnostics request to the client.

textDocument/didSave

When the server is using Push Mode and configuration run is set to onSave, the server will validate the text document and send a textDocument/publishDiagnostics request to the client.

textDocument/didChange

The server will cache the internal content of the text document. When the server is using Push Mode and configuration run is set to onType, the server will validate the text document and send a textDocument/publishDiagnostics request to the client.

textDocument/didClose

It will remove the reference internal.

textDocument/codeAction

Returns a list of CodeAction

textDocument/diagnostics

Should only be used when the server is using the Pull Mode for diagnostics. The server will lint the file and report the diagnostics back to the client.

textDocument/formatting

Returns a list of TextEdit

Optional LSP Specifications from Client

Client

textDocument/publishDiagnostics

When the server is using Push Mode it will lint the file onOpen and onChange or onSave (depending on the configuration the client passed).

workspace/diagnostic/refresh

When the server is using the Pull Mode it will request the client sometimes to re-pull the diagnostics. This will happen when changing watched files or specific server configurations.

client/registerCapability

The server will send this request to watch for specific files. The method workspace/didChangeWatchedFiles will be used with custom registerOptions.

client/unregisterCapability

The server will send this request to stop watching for specific files. The id will match from client/registerCapability.

Workspace

workspace/configuration

The server will request workspace configurations. The server expects the received items to match the order of the requested items. Only will be requested when the ClientCapabilities has workspace.configuration set to true.

The client can return a response like:

[
  {
    "run": "onType",
    "configPath": null,
    "tsConfigPath": null,
    "unusedDisableDirectives": "allow",
    "typeAware": false,
    "disableNestedConfig": false,
    "fixKind": "safe_fix",
    "rulesCustomization": {},
    "fmt.configPath": null,
    "fmt.disableNestedConfig": false
  }
]