@tsrx/language-server 0.5.2 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +206 -4
- package/dist/language-server.js +1 -1
- package/dist/language-server.js.map +1 -1
- package/dist/{server-C9rY0GfG.js → server-BnzVhVsF.js} +5067 -3549
- package/dist/server-BnzVhVsF.js.map +1 -0
- package/dist/server.js +2 -1
- package/package.json +13 -6
- package/types/server.d.ts +15 -1
- package/dist/server-C9rY0GfG.js.map +0 -1
package/README.md
CHANGED
|
@@ -5,7 +5,8 @@
|
|
|
5
5
|
|
|
6
6
|
Language Server Protocol implementation for `.tsrx` files. It uses Volar and
|
|
7
7
|
TypeScript to provide diagnostics, completions, hover information, navigation,
|
|
8
|
-
document symbols, highlighting, and automatic closing tags.
|
|
8
|
+
document symbols, highlighting, and automatic closing tags. It formats `.tsrx`
|
|
9
|
+
files with the project's Prettier (see [Formatting](#formatting)).
|
|
9
10
|
|
|
10
11
|
The language server resolves the compiler selected by the active TypeScript
|
|
11
12
|
project, so the same tooling works with React, Preact, Solid, Vue, Ripple, Octane,
|
|
@@ -16,6 +17,8 @@ the file is compiled by the Ripple target.
|
|
|
16
17
|
|
|
17
18
|
```bash
|
|
18
19
|
npm install --global @tsrx/language-server
|
|
20
|
+
# or
|
|
21
|
+
pnpm add --global @tsrx/language-server
|
|
19
22
|
```
|
|
20
23
|
|
|
21
24
|
Start the server over stdio:
|
|
@@ -28,15 +31,214 @@ It can also be run without a global installation:
|
|
|
28
31
|
|
|
29
32
|
```bash
|
|
30
33
|
npx @tsrx/language-server --stdio
|
|
34
|
+
# or
|
|
35
|
+
pnpm dlx @tsrx/language-server --stdio
|
|
31
36
|
```
|
|
32
37
|
|
|
33
38
|
Configure your editor's LSP client for `*.tsrx` files with the language ID `tsrx`.
|
|
34
|
-
|
|
39
|
+
|
|
40
|
+
## Which TypeScript it uses
|
|
41
|
+
|
|
42
|
+
When the editor does not choose a backend, the server runs the `classic` backend,
|
|
43
|
+
which needs a `typescript` package. On the `native` backend (TypeScript 7) and the
|
|
44
|
+
`plugin` backend (which VS Code uses), it loads no TypeScript and searches for
|
|
45
|
+
none.
|
|
46
|
+
|
|
47
|
+
On the `classic` backend, it uses the first `typescript` it finds:
|
|
48
|
+
|
|
49
|
+
1. The `typescript.tsdk` initialization option, when the editor passes one: the
|
|
50
|
+
`lib` folder of a TypeScript installation.
|
|
51
|
+
2. The project's: `node_modules/typescript` in each open workspace folder and its
|
|
52
|
+
parent folders, the way Node finds a package. The first folder that has one
|
|
53
|
+
wins. When the editor names no folder, the server searches from the folder it
|
|
54
|
+
was started in.
|
|
55
|
+
3. The one next to the server: `node_modules/typescript` from the server's own
|
|
56
|
+
folder up.
|
|
57
|
+
|
|
58
|
+
Any version below 7 works. `typescript` is an optional peer dependency, so npm and
|
|
59
|
+
pnpm do not install one with the server. Install it in the project:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npm install -D typescript
|
|
63
|
+
# or
|
|
64
|
+
pnpm add -D typescript
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
When the server finds no `typescript`, or finds TypeScript 7, it still starts and
|
|
68
|
+
shows one warning that says what it found and what to do. `.tsrx` files then get
|
|
69
|
+
no type checking, hover or completions. TSRX compile errors, CSS in `<style>`, the
|
|
70
|
+
outline, formatting and closing tags still work.
|
|
71
|
+
|
|
72
|
+
To use another TypeScript than the one it finds, pass that TypeScript's `lib`
|
|
73
|
+
folder:
|
|
74
|
+
|
|
75
|
+
```jsonc
|
|
76
|
+
// LSP initialize params
|
|
77
|
+
{
|
|
78
|
+
"initializationOptions": {
|
|
79
|
+
"typescript": { "tsdk": "/path/to/node_modules/typescript/lib" },
|
|
80
|
+
},
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### TypeScript 7
|
|
85
|
+
|
|
86
|
+
TypeScript 7's npm package is the native compiler and has no JavaScript API, so
|
|
87
|
+
the `classic` backend cannot run it. For `.tsrx` files on TypeScript 7:
|
|
88
|
+
|
|
89
|
+
1. Install TypeScript `7.1.0-dev.20260923.1` or newer and
|
|
90
|
+
[`@tsrx/content-mapper`](https://github.com/tsrx-org/tsrx/tree/main/packages/content-mapper)
|
|
91
|
+
in the project, and declare the mapper in `tsconfig.json`:
|
|
92
|
+
|
|
93
|
+
```jsonc
|
|
94
|
+
{
|
|
95
|
+
"tsrx": { "compiler": "@tsrx/react" },
|
|
96
|
+
"contentMappers": [
|
|
97
|
+
{ "package": "@tsrx/content-mapper", "extensions": [".tsrx"] },
|
|
98
|
+
],
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
2. Have the editor run TypeScript 7's language server, `tsc --lsp --stdio`, for
|
|
103
|
+
`.tsrx` files, with the initialization option `runExternalCode: true`. It
|
|
104
|
+
serves types, hover, completions and errors, TSRX compile errors included.
|
|
105
|
+
3. Run this server next to it with `--typescript-backend=native`, for what
|
|
106
|
+
TypeScript 7 does not do: CSS in `<style>`, the outline, formatting and closing
|
|
107
|
+
tags. It loads no TypeScript in that mode.
|
|
108
|
+
|
|
109
|
+
## TypeScript backends
|
|
110
|
+
|
|
111
|
+
The server runs beside one of two TypeScript backends. Never run both on the same
|
|
112
|
+
file.
|
|
113
|
+
|
|
114
|
+
- `classic` (default): the server hosts TypeScript itself through Volar and serves
|
|
115
|
+
every feature for `.tsrx` files, including type-aware ones. Which TypeScript it
|
|
116
|
+
hosts: [Which TypeScript it uses](#which-typescript-it-uses).
|
|
117
|
+
- `native`: TypeScript 7 owns every TypeScript feature for `.tsrx` files through
|
|
118
|
+
[`@tsrx/content-mapper`](https://github.com/tsrx-org/tsrx/tree/main/packages/content-mapper)
|
|
119
|
+
(diagnostics including TSRX compile errors, hover, completions, signature help,
|
|
120
|
+
definitions, references, rename, code actions, auto-import, inlay hints,
|
|
121
|
+
semantic tokens). The TSRX server is slimmed down to what TypeScript does not
|
|
122
|
+
own: TSRX snippet completions (Ripple-gated), CSS in `<style>` blocks, document
|
|
123
|
+
symbols, auto-closing tags, CSS-class hover and definition, and keyword
|
|
124
|
+
highlights. `volar-service-typescript` is never loaded in this mode.
|
|
125
|
+
- `plugin`: the editor's own tsserver owns every TypeScript feature for `.tsrx`
|
|
126
|
+
files through `@tsrx/typescript-plugin` (VS Code on TypeScript 5.9 or 6, where
|
|
127
|
+
the extension hands the plugin to VS Code's tsserver). The server is as slim as
|
|
128
|
+
on `native` but also reports the TSRX compile errors, which a tsserver plugin
|
|
129
|
+
cannot.
|
|
130
|
+
|
|
131
|
+
Select the backend with a command-line flag or an initialization option (the flag
|
|
132
|
+
wins):
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
tsrx-language-server --stdio --typescript-backend=native
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
```jsonc
|
|
139
|
+
// LSP initialize params
|
|
140
|
+
{ "initializationOptions": { "typescriptBackend": "native" } }
|
|
141
|
+
// or, on the classic backend, the TypeScript to host:
|
|
142
|
+
{ "initializationOptions": { "typescript": { "tsdk": "/path/to/node_modules/typescript/lib" } } }
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Use `native` only when the same editor also runs TypeScript 7's language server
|
|
146
|
+
with `initializationOptions.runExternalCode: true` and the project declares the
|
|
147
|
+
content mapper in `tsconfig.json`; otherwise `.tsrx` files get no type
|
|
148
|
+
information. The VS Code extension selects the backend for you. VS Code users can
|
|
149
|
+
install the
|
|
35
150
|
[TSRX Syntax for VS Code](https://marketplace.visualstudio.com/items?itemName=TSRX.tsrx-vscode-plugin),
|
|
36
151
|
which bundles and starts this server automatically. Zed users can install the
|
|
37
152
|
[TSRX extension for Zed](https://zed.dev/extensions/tsrx), which also starts this
|
|
38
153
|
server automatically.
|
|
39
154
|
|
|
155
|
+
## Formatting
|
|
156
|
+
|
|
157
|
+
The server formats `.tsrx` files (`textDocument/formatting`, and
|
|
158
|
+
`textDocument/rangeFormatting` for a selection or a paste) with the project's own
|
|
159
|
+
`prettier` and
|
|
160
|
+
[`@tsrx/prettier-plugin`](https://github.com/tsrx-org/tsrx/tree/main/packages/prettier-plugin),
|
|
161
|
+
on every backend.
|
|
162
|
+
|
|
163
|
+
1. Install both in the project:
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
npm install -D prettier @tsrx/prettier-plugin
|
|
167
|
+
# or
|
|
168
|
+
pnpm add -D prettier @tsrx/prettier-plugin
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
2. Run your editor's format command (whole file or selection), or turn on format
|
|
172
|
+
on save or on paste.
|
|
173
|
+
|
|
174
|
+
How it formats:
|
|
175
|
+
|
|
176
|
+
- The server bundles no Prettier. It uses the project's copy, so the editor gives
|
|
177
|
+
the same result as the project's `prettier` command. Prettier 3.6 or newer is
|
|
178
|
+
necessary (the plugin's peer range).
|
|
179
|
+
- The server looks for both packages in the `node_modules` folders above the file,
|
|
180
|
+
and nowhere else (not `NODE_PATH`).
|
|
181
|
+
- The server adds the plugin and the `tsrx` parser itself. A `.tsrx` file formats
|
|
182
|
+
even when the Prettier config does not list the plugin. The `prettier` command
|
|
183
|
+
still needs the plugin in the config.
|
|
184
|
+
- The Prettier config (`.prettierrc` or another config file), `.editorconfig`, and
|
|
185
|
+
the nearest `.prettierignore` apply, as on the command line. The editor's tab
|
|
186
|
+
size and its choice of tabs or spaces apply only when the project has no
|
|
187
|
+
Prettier config and no `.editorconfig`.
|
|
188
|
+
|
|
189
|
+
When formatting cannot run:
|
|
190
|
+
|
|
191
|
+
- **A package is missing, or Prettier is older than 3.6:** the server returns no
|
|
192
|
+
edits. It shows a message once per project (`window/showMessage`), for example:
|
|
193
|
+
|
|
194
|
+
> To format .tsrx files, TSRX needs prettier and @tsrx/prettier-plugin in this
|
|
195
|
+
> project. To install them, run: npm install -D prettier @tsrx/prettier-plugin
|
|
196
|
+
|
|
197
|
+
The install command matches the project's package manager, from the nearest
|
|
198
|
+
lockfile (pnpm, Yarn, Bun or npm; npm without a lockfile).
|
|
199
|
+
|
|
200
|
+
The server does not send an error response, because with format on save the
|
|
201
|
+
editor would report a failure on every save.
|
|
202
|
+
|
|
203
|
+
- **Prettier cannot parse the file**, which happens while you type: the server
|
|
204
|
+
returns no edits and writes the error to its log only.
|
|
205
|
+
|
|
206
|
+
To turn formatting off, set `tsrx.format.enable` to `false`. The server reads it
|
|
207
|
+
through `workspace/configuration`.
|
|
208
|
+
|
|
209
|
+
Other formatters for `.tsrx` files return no edits:
|
|
210
|
+
|
|
211
|
+
- **TypeScript 7** (`tsc --lsp`) always offers a formatter for content-mapped
|
|
212
|
+
files such as `.tsrx`, and a content mapper cannot turn it off yet
|
|
213
|
+
([microsoft/TypeScript#64579](https://github.com/microsoft/TypeScript/issues/64579)).
|
|
214
|
+
In an editor that runs `tsc --lsp` for `.tsrx` files, choose the TSRX language
|
|
215
|
+
server as the formatter.
|
|
216
|
+
- **VS Code's own TypeScript** (5.9 or 6) offers no `.tsrx` formatter, unless
|
|
217
|
+
`js/ts.format.enabled` is set in the settings.
|
|
218
|
+
|
|
219
|
+
In VS Code, TSRX is the default formatter for `.tsrx` files, so neither gets in
|
|
220
|
+
the way.
|
|
221
|
+
|
|
222
|
+
## Restarts after package changes
|
|
223
|
+
|
|
224
|
+
When a `package.json` or a lockfile changes (`pnpm install`, for example), the
|
|
225
|
+
server must restart to load the TSRX compiler again. By default it exits with code
|
|
226
|
+
0, and the editor must start it again.
|
|
227
|
+
|
|
228
|
+
An editor that can restart the server itself sets the `restartNotification`
|
|
229
|
+
initialization option. The server then sends a `tsrx/restartServer` notification
|
|
230
|
+
and keeps running until the editor stops it (`shutdown`, then `exit`) and starts
|
|
231
|
+
it again. The VS Code extension does this:
|
|
232
|
+
|
|
233
|
+
```jsonc
|
|
234
|
+
// LSP initialize params
|
|
235
|
+
{ "initializationOptions": { "restartNotification": true } }
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## More
|
|
239
|
+
|
|
40
240
|
See the [TSRX documentation](https://tsrx.dev/) and
|
|
41
|
-
[`@tsrx/typescript-plugin`](
|
|
42
|
-
selection and TypeScript configuration
|
|
241
|
+
[`@tsrx/typescript-plugin`](https://github.com/tsrx-org/tsrx/tree/main/packages/typescript-plugin)
|
|
242
|
+
for target compiler selection and TypeScript configuration, and
|
|
243
|
+
[`@tsrx/content-mapper`'s `ROLLOUT.md`](https://github.com/tsrx-org/tsrx/blob/main/packages/content-mapper/ROLLOUT.md)
|
|
244
|
+
for the migration, rollback and default-backend decision behind the two backends.
|
package/dist/language-server.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"language-server.js","names":["createTsrxLanguageServer"],"sources":["../src/language-server.js"],"sourcesContent":["#!/usr/bin/env node\n\nimport { createTsrxLanguageServer } from './server.js';\n\ncreateTsrxLanguageServer();\n"],"mappings":";;;;AAIAA,
|
|
1
|
+
{"version":3,"file":"language-server.js","names":["createTsrxLanguageServer"],"sources":["../src/language-server.js"],"sourcesContent":["#!/usr/bin/env node\n\nimport { createTsrxLanguageServer } from './server.js';\n\ncreateTsrxLanguageServer();\n"],"mappings":";;;;AAIAA,wCAAyB"}
|