Skip to content

Commit 1a1fc8f

Browse files
pmiziopmizio
committed
docs: README.md (#45)
1 parent f82d8b7 commit 1a1fc8f

File tree

2 files changed

+195
-46
lines changed

2 files changed

+195
-46
lines changed

‎.markdownlint-cli2.yaml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
config:
2-
# MD052/reference-links-images - Reference links and images should use a label that is defined
2+
MD013:
3+
line_length: 100
4+
tables: false
5+
MD033: false
6+
MD040: false
37
MD052: false
48

59
ignores: ["**/node_modules/**"]

‎README.md

Lines changed: 190 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,50 @@
1-
# typescript-tools.nvim
1+
<h1 align="center">typescript-tools.nvim</h1>
2+
<p align="center"><sup>⚡ TypeScript integration NeoVim deserves ⚡</sup></p>
23

3-
## TODO: description
4+
### 🚧 Warning 🚧
5+
6+
Please note that the plugin is currently in the early beta version, which means you may encounter
7+
bugs.
8+
9+
### ⁉️ Why?
10+
11+
1. Drop in, pure lua replacement for `typescript-language-server`
12+
2. If you work on a large TS/JS project, you probably understand why this plugin came into existence.
13+
The `typescript-language-server` can be extremely slow in such projects,
14+
and it often fails to provide accurate completions or just crash.
15+
16+
### ✨ Features
17+
18+
- ⚡ Blazingly fast, thanks to the utilization of the native Tsserver communication protocol,
19+
similar to Visual Studio Code
20+
- 🪭 Supports a wide range of TypeScript versions 4.0 and above
21+
- 🌍 Supports the nvim LSP plugin ecosystem
22+
- 🔀 Supports multiple instances of Tsserver
23+
- 💻 Supports both local and global installations of TypeScript
24+
- 💅 Provides out-of-the-box support for styled-components, which is not enabled by default
25+
(see Installation and [Configuration](#-styled-components-support))
26+
- ✨ Improved code refactor capabilities e.g. extracting to variable or function
27+
28+
![code_action](https://github.com/pmizio/typescript-tools.nvim/assets/4346598/50f87c54-c286-473d-ba3d-886ac97ca072)
29+
30+
### 🚀 How it works?
31+
32+
<details>
33+
<summary>
34+
If you're interested in learning more about the technical details of the plugin, you can click here.
35+
</summary>
36+
<p>
37+
<br>
38+
This plugin functions exactly like the bundled TypeScript support extension in Visual Studio Code.
39+
Thanks to the new (0.8.0) NeoVim API, it is now possible to pass a Lua function as the LSP start
40+
command. As a result, the plugin spawns a custom version of the I/O loop to communicate directly
41+
with Tsserver using its native protocol, without the need for any additional proxy.
42+
The Tsserver protocol, which is a JSON-based communication protocol, likely served as inspiration
43+
for the LSP. However, it is incompatible with the LSP. To address this, the I/O loop provided by
44+
this plugin features a translation layer that converts all messages to and from the Tsserver format.
45+
</p>
46+
47+
In summary, the architecture of this plugin can be visualized as shown in the diagram below:
448

549
```lua
650
NeoVim Tsserver Instance
@@ -26,41 +70,70 @@
2670
└────────────────────────────────────────────┘ └────────────────┘
2771
```
2872

29-
## Supported lsp methods
30-
31-
| Status | Request |
32-
| ------ | --------------------------------------------------------- |
33-
| ✅ | textDocument/completion |
34-
| ✅ | textDocument/hover |
35-
| ✅ | textDocument/rename |
36-
| ✅ | textDocument/publishDiagnostics |
37-
| ✅ | textDocument/signatureHelp |
38-
| ✅ | textDocument/references |
39-
| ✅ | textDocument/definition |
40-
| ✅ | textDocument/typeDefinition |
41-
| ✅ | textDocument/implementation |
42-
| ✅ | textDocument/documentSymbol |
43-
| ✅ | textDocument/documentHighlight |
44-
| ✅ | textDocument/codeAction |
45-
| ✅ | textDocument/formatting |
46-
| ✅ | textDocument/rangeFormatting |
47-
| ✅ | textDocument/foldingRange |
48-
| ✅ | textDocument/semanticTokens/full (supported from TS v4.1) |
49-
| ✅ | textDocument/inlayHint (supported from TS v4.4) |
50-
| ✅ | callHierarchy/incomingCalls |
51-
| ✅ | callHierarchy/outgoingCalls |
52-
| ✅ | workspace/symbol |
53-
| ✅ | workspace/willRenameFiles |
54-
| ❌ | workspace/applyEdit - N/A |
55-
| ❌ | textDocument/declaration - N/A |
56-
| ❌ | window/logMessage - N/A |
57-
| ❌ | window/showMessage - N/A |
58-
| ❌ | window/showMessageRequest - N/A |
59-
60-
### Configuration
73+
</details>
74+
75+
### 📦 Installation
76+
77+
> ❗️ IMPORTANT: As mentioned earlier, this plugin serves as a replacement for `typescript-language-server`,
78+
> so you should remove the `nvim-lspconfig` setup for it.
79+
80+
#### ⚡️ Requirements
81+
82+
- NeoVim >= 0.8.0
83+
- [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig)
84+
- [plenary.nvim](https://github.com/nvim-lua/plenary.nvim)
85+
- TypeScript >= 4.0
86+
- Node supported suitable for TypeScript version you use
87+
88+
#### [lazy.nvim](https://github.com/folke/lazy.nvim)
89+
90+
```lua
91+
{
92+
"pmizio/typescript-tools.nvim",
93+
dependencies = { "nvim-lua/plenary.nvim", "neovim/nvim-lspconfig" },
94+
opts = {},
95+
}
96+
```
97+
98+
#### [packer.nvim](https://github.com/wbthomason/packer.nvim)
99+
100+
```lua
101+
use {
102+
"pmizio/typescript-tools.nvim"
103+
requires = { "nvim-lua/plenary.nvim", "neovim/nvim-lspconfig" },
104+
config = function()
105+
require("typescript-tools").setup {}
106+
end,
107+
}
108+
```
109+
110+
### ⚙️ Configuration
111+
112+
The parameters passed into the `setup` function are also passed to the standard `nvim-lspconfig`
113+
server `setup`, allowing you to use the same settings here.
114+
But you can pass plugin-specific options through the `settings` parameter, which defaults to:
115+
116+
```lua
117+
require("typescript-tools").setup {
118+
on_attach = function() ... end,
119+
...
120+
settings = {
121+
-- spawn additional tsserver instance to calculate diagnostics on it
122+
separate_diagnostic_server = true,
123+
-- "change"|"insert_leave" determine when the client asks the server about diagnostic
124+
publish_diagnostic_on = "insert_leave",
125+
-- specify a list of plugins to load by tsserver, e.g., for support `styled-components`
126+
-- (see 💅 `styled-components` support section)
127+
tsserver_plugins = {},
128+
-- described below
129+
tsserver_format_options = {},
130+
tsserver_file_preferences = {},
131+
},
132+
}
133+
```
61134

62135
You can pass custom configuration options that will be passed to `tsserver`
63-
instance. You can find available options in `typescript` repositorory (e.g.
136+
instance. You can find available options in `typescript` repository (e.g.
64137
for version 5.0.4 of typescript):
65138

66139
- [tsserver_file_preferences](https://github.com/microsoft/TypeScript/blob/v5.0.4/src/server/protocol.ts#L3439)
@@ -69,7 +142,7 @@ for version 5.0.4 of typescript):
69142
To pass those options to plugin pass them to the plugin `setup` function:
70143

71144
```lua
72-
typescript_tools.setup({
145+
require("typescript-tools").setup {
73146
settings = {
74147
...
75148
tsserver_file_preferences = {
@@ -84,31 +157,103 @@ typescript_tools.setup({
84157
...
85158
}
86159
},
87-
})
160+
}
88161
```
89162

90163
The default values for `preferences` and `format_options` are in [this file](https://github.com/pmizio/typescript-tools.nvim/blob/master/lua/typescript-tools/protocol/text_document/did_open.lua#L8)
91164

92-
## Development
165+
#### 💅 `styled-components` support
166+
167+
<details>
168+
<summary>Show more</summary>
169+
<p>
170+
<br>
171+
To get IntelliSense for <code>styled-components</code>, you need to install the tsserver plugin
172+
globally, which enables support for it:
173+
</p>
174+
175+
```
176+
npm i -g typescript-styled-plugin
177+
```
178+
179+
Now, you need to load the plugin by modifying the `settings` object as follows:
180+
181+
```lua
182+
require("typescript-tools").setup {
183+
settings = {
184+
...
185+
tsserver_plugins = { "typescript-styled-plugin" },
186+
},
187+
}
188+
```
189+
190+
</details>
191+
192+
## Supported LSP methods
193+
194+
| Status | Request |
195+
| ------ | ------------------------------------------------------------------------------------- |
196+
| ✅ | textDocument/completion |
197+
| ✅ | textDocument/hover |
198+
| ✅ | textDocument/rename |
199+
| ✅ | textDocument/publishDiagnostics |
200+
| ✅ | textDocument/signatureHelp |
201+
| ✅ | textDocument/references |
202+
| ✅ | textDocument/definition |
203+
| ✅ | textDocument/typeDefinition |
204+
| ✅ | textDocument/implementation |
205+
| ✅ | textDocument/documentSymbol |
206+
| ✅ | textDocument/documentHighlight |
207+
| ✅ | textDocument/codeAction |
208+
| ✅ | textDocument/formatting |
209+
| ✅ | textDocument/rangeFormatting |
210+
| ✅ | textDocument/foldingRange |
211+
| ✅ | textDocument/semanticTokens/full (supported from TS v4.1) |
212+
| ✅ | textDocument/inlayHint (supported from TS v4.4) |
213+
| ✅ | callHierarchy/incomingCalls |
214+
| ✅ | callHierarchy/outgoingCalls |
215+
| 🚧 | textDocument/codeLens([#39](https://github.com/pmizio/typescript-tools.nvim/pull/39)) |
216+
| 🚧 | textDocument/linkedEditingRange (planned) |
217+
| ✅ | workspace/symbol |
218+
| ✅ | workspace/willRenameFiles |
219+
| ❌ | workspace/applyEdit - N/A |
220+
| ❌ | textDocument/declaration - N/A |
221+
| ❌ | window/logMessage - N/A |
222+
| ❌ | window/showMessage - N/A |
223+
| ❌ | window/showMessageRequest - N/A |
224+
225+
## 🚦 Roadmap
226+
227+
- `textDocument/codeLens` - [#39](https://github.com/pmizio/typescript-tools.nvim/pull/39)
228+
- `textDocument/linkedEditingRange` - [#32](https://github.com/pmizio/typescript-tools.nvim/pull/32)
229+
- Embedded language support(JS inside of HTML) - [#43](https://github.com/pmizio/typescript-tools.nvim/pull/43)
230+
231+
## 🔨 Development
93232

94233
Useful links:
95234

96235
- [nvim-lua-guide](https://github.com/nanotee/nvim-lua-guide)
97236
- [plenary.nvim](https://github.com/nvim-lua/plenary.nvim)
98237

99-
### Run tests
238+
### 🐛 Run tests
100239

101-
Running tests requires [plenary.nvim](https://github.com/nvim-lua/plenary.nvim)
102-
to be checked out in the parent directory of _this_ repository.
103-
Make sure you have [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig) plugin.
104-
You can then run:
240+
The unit testing environment is automatically bootstrapped, just run:
105241

106-
```bash
242+
```
107243
make test
108244
```
109245

110246
Or if you want to run a single test file:
111247

112-
```bash
248+
```
113249
make file=test_spec.lua test
114250
```
251+
252+
## 💐 Credits
253+
254+
- [null-ls.nvim](https://github.com/jose-elias-alvarez/null-ls.nvim)
255+
\- for the idea to monkeypatch nvim API to start a custom LSP I/O loop
256+
- [typescript-language-server](https://github.com/typescript-language-server/typescript-language-server)
257+
\- for ideas on how to translate certain Tsserver responses
258+
- [Visual Studio Code(TypeScript extension)](https://github.com/microsoft/vscode/tree/main/extensions/typescript-language-features)
259+
\- for insights on using the Tsserver protocol and performance optimizations

0 commit comments

Comments
 (0)