Integrating with Pkl Language Server
Pkl Language Server is a low-level tool that is meant to be integrated with editors by way of plugins.
The documentation below is intended for plugin implementors.
Distribution
Pkl Language Server is published to Maven Central, and also as releases on GitHub.
It is recommended that the jar file be bundled into an editor plugin’s package contents.
Running Pkl Language Server
To run the server, provide the jar as an argument to Java. For example:
java -jar path/to/pkl-lsp.jar
Pkl Language Server requires Java 22 or higher.
We plan on providing native binaries in the future. Follow #60 to stay updated on its progress. |
pkl-lsp
URI scheme
The server uses the pkl-lsp
scheme to represent sources from the standard library, as well as other types of non-file Pkl sources.
For example, the pkl:base
standard library module is surfaced to editors as URI pkl-lsp://stdlib/base.pkl
.
Custom client options
When starting the server, additional client options can be provided to configure the behavior of the language server.
These options are provided in the initializationOptions
section of the Initialize Request.
renderOpenFileCommandInDocs
Type: Boolean
Cause the server to render links within documentation using the command:pkl.open.file
URI.
If enabled, clients are expected to implement the command pkl.open.file
.
extendedClientCapabilities
Tell the server that the client supports additional capabilities made available by Pkl Language Server.
Name | Description |
---|---|
|
The client supports the |
The client supports the |
Pkl CLI configuration
To support flows like sync projects, and package downloading, the server will look for a path to the Pkl CLI.
By default, the server will look for the CLI within the environment’s $PATH
.
If the client supports the Configuration Request, it will look for the configuration value pkl.cli.path
at scope Pkl
.
Additional message types
Pkl Language Server extends the Language Server Protocol with custom message types.
These message types are optional, and enhance the integration with an editor.
File Contents Request
Method: pkl/fileContents
Body: TextDocumentIdentifier
Read text contents of the document identified by the specified params..
Sync Projects Request
Method: pkl/syncProjects
Body: Any
Sync any PklProject
defined in the workspace.
This allows the server to understand imports declared using dependency notation.
Commands
The following commands can optionally be implemented. If implemented, and the capability is made known to Pkl Language Server, the server will issue Execute Command requests.
Name | Arguments | Description |
---|---|---|
|
Send a File Contents Request to Pkl Language Server, and open the resulting contents in an editor pane at the indicated line and column. |
|
|
|
Send a Sync Projects Request to Pkl Language Server. |
|
|
Open the editor’s settings/configuration panel at the configuration path. |
|
|
Send a Download Package Request to Pkl Language Server. |