@tsrx/language-server 0.5.1 → 0.6.0

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,142 @@ 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
+ The `classic` backend hosts TypeScript's JavaScript API,
41
+ `typescript@^5.9.3 || ^6.0.0` (the peer dependency range also admits TypeScript 7
42
+ from `7.1.0-dev.20260923.1`, for the `native` backend); it refuses to initialize
43
+ with an explanation when the project's only `typescript` is the native TypeScript
44
+ 7 package (a launcher without a JavaScript API). The `native` backend loads no
45
+ TypeScript at all: it reads `tsconfig.json` and resolves compilers through
46
+ `@tsrx/typescript-plugin`'s own reader and runs on Volar's plain project host, so
47
+ TypeScript 7 can be the only TypeScript in the project.
48
+
49
+ ## TypeScript backends
50
+
51
+ The server runs beside one of two TypeScript backends. Never run both on the same
52
+ file.
53
+
54
+ - `classic` (default): the server hosts TypeScript (5.9 or 6) itself through Volar
55
+ and serves every feature for `.tsrx` files, including type-aware ones. Which
56
+ installation it hosts comes from the Volar-style `typescript.tsdk`
57
+ initialization option, the absolute path of a TypeScript `lib` directory (the
58
+ one containing `typescript.js`); the VS Code extension passes the TypeScript VS
59
+ Code runs for the workspace. Without the option the server loads the
60
+ `typescript` package resolvable from its own location (the peer dependency).
61
+ - `native`: TypeScript 7 owns every TypeScript feature for `.tsrx` files through
62
+ [`@tsrx/content-mapper`](https://github.com/tsrx-org/tsrx/tree/main/packages/content-mapper)
63
+ (diagnostics including TSRX compile errors, hover, completions, signature help,
64
+ definitions, references, rename, code actions, auto-import, inlay hints,
65
+ semantic tokens). The TSRX server is slimmed down to what TypeScript does not
66
+ own: TSRX snippet completions (Ripple-gated), CSS in `<style>` blocks, document
67
+ symbols, auto-closing tags, CSS-class hover and definition, and keyword
68
+ highlights. `volar-service-typescript` is never loaded in this mode.
69
+ - `plugin`: the editor's own tsserver owns every TypeScript feature for `.tsrx`
70
+ files through `@tsrx/typescript-plugin` (VS Code on TypeScript 5.9 or 6, where
71
+ the extension hands the plugin to VS Code's tsserver). The server is as slim as
72
+ on `native` but also reports the TSRX compile errors, which a tsserver plugin
73
+ cannot.
74
+
75
+ Select the backend with a command-line flag or an initialization option (the flag
76
+ wins):
77
+
78
+ ```bash
79
+ tsrx-language-server --stdio --typescript-backend=native
80
+ ```
81
+
82
+ ```jsonc
83
+ // LSP initialize params
84
+ { "initializationOptions": { "typescriptBackend": "native" } }
85
+ // or, on the classic backend, the TypeScript to host:
86
+ { "initializationOptions": { "typescript": { "tsdk": "/path/to/node_modules/typescript/lib" } } }
87
+ ```
88
+
89
+ Use `native` only when the same editor also runs TypeScript 7's language server
90
+ with `initializationOptions.runExternalCode: true` and the project declares the
91
+ content mapper in `tsconfig.json`; otherwise `.tsrx` files get no type
92
+ information. The VS Code extension selects the backend for you. VS Code users can
93
+ install the
35
94
  [TSRX Syntax for VS Code](https://marketplace.visualstudio.com/items?itemName=TSRX.tsrx-vscode-plugin),
36
95
  which bundles and starts this server automatically. Zed users can install the
37
96
  [TSRX extension for Zed](https://zed.dev/extensions/tsrx), which also starts this
38
97
  server automatically.
39
98
 
99
+ ## Formatting
100
+
101
+ The server formats `.tsrx` files (`textDocument/formatting`, and
102
+ `textDocument/rangeFormatting` for a selection or a paste) with the project's own
103
+ `prettier` and
104
+ [`@tsrx/prettier-plugin`](https://github.com/tsrx-org/tsrx/tree/main/packages/prettier-plugin),
105
+ on every backend.
106
+
107
+ 1. Install both in the project:
108
+
109
+ ```bash
110
+ npm install -D prettier @tsrx/prettier-plugin
111
+ # or
112
+ pnpm add -D prettier @tsrx/prettier-plugin
113
+ ```
114
+
115
+ 2. Run your editor's format command (whole file or selection), or turn on format
116
+ on save or on paste.
117
+
118
+ How it formats:
119
+
120
+ - The server bundles no Prettier. It uses the project's copy, so the editor gives
121
+ the same result as the project's `prettier` command. Prettier 3.6 or newer is
122
+ necessary (the plugin's peer range).
123
+ - The server looks for both packages in the `node_modules` folders above the file,
124
+ and nowhere else (not `NODE_PATH`).
125
+ - The server adds the plugin and the `tsrx` parser itself. A `.tsrx` file formats
126
+ even when the Prettier config does not list the plugin. The `prettier` command
127
+ still needs the plugin in the config.
128
+ - The Prettier config (`.prettierrc` or another config file), `.editorconfig`, and
129
+ the nearest `.prettierignore` apply, as on the command line. The editor's tab
130
+ size and its choice of tabs or spaces apply only when the project has no
131
+ Prettier config and no `.editorconfig`.
132
+
133
+ When formatting cannot run:
134
+
135
+ - **A package is missing, or Prettier is older than 3.6:** the server returns no
136
+ edits. It shows a message once per project (`window/showMessage`), for example:
137
+
138
+ > To format .tsrx files, TSRX needs prettier and @tsrx/prettier-plugin in this
139
+ > project. To install them, run: npm install -D prettier @tsrx/prettier-plugin
140
+
141
+ The install command matches the project's package manager, from the nearest
142
+ lockfile (pnpm, Yarn, Bun or npm; npm without a lockfile).
143
+
144
+ The server does not send an error response, because with format on save the
145
+ editor would report a failure on every save.
146
+
147
+ - **Prettier cannot parse the file**, which happens while you type: the server
148
+ returns no edits and writes the error to its log only.
149
+
150
+ To turn formatting off, set `tsrx.format.enable` to `false`. The server reads it
151
+ through `workspace/configuration`.
152
+
153
+ Other formatters for `.tsrx` files return no edits:
154
+
155
+ - **TypeScript 7** (`tsc --lsp`) always offers a formatter for content-mapped
156
+ files such as `.tsrx`, and a content mapper cannot turn it off yet
157
+ ([microsoft/TypeScript#64579](https://github.com/microsoft/TypeScript/issues/64579)).
158
+ In an editor that runs `tsc --lsp` for `.tsrx` files, choose the TSRX language
159
+ server as the formatter.
160
+ - **VS Code's own TypeScript** (5.9 or 6) offers no `.tsrx` formatter, unless
161
+ `js/ts.format.enabled` is set in the settings.
162
+
163
+ In VS Code, TSRX is the default formatter for `.tsrx` files, so neither gets in
164
+ the way.
165
+
166
+ ## More
167
+
40
168
  See the [TSRX documentation](https://tsrx.dev/) and
41
- [`@tsrx/typescript-plugin`](../typescript-plugin/README.md) for target compiler
42
- selection and TypeScript configuration.
169
+ [`@tsrx/typescript-plugin`](https://github.com/tsrx-org/tsrx/tree/main/packages/typescript-plugin)
170
+ for target compiler selection and TypeScript configuration, and
171
+ [`@tsrx/content-mapper`'s `ROLLOUT.md`](https://github.com/tsrx-org/tsrx/blob/main/packages/content-mapper/ROLLOUT.md)
172
+ 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-Dn5OWBDY.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"}