@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 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
- VS Code users can install the
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`](../typescript-plugin/README.md) for target compiler
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.
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- const require_server = require('./server-C9rY0GfG.js');
2
+ const require_server = require('./server-BnzVhVsF.js');
3
3
 
4
4
  //#region src/language-server.js
5
5
  require_server.createTsrxLanguageServer();
@@ -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,yCAA0B"}
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"}