Skip to content

Commit 3466228

Browse files
leonidazclaude
andcommitted
docs(vscode-plugin): plainer TypeScript 7 sections and a legacy settings note
- Rewrite the text after the setup steps in short sentences, with headings, lists, and links for the upstream issues. - Correct the "server plugins will not be loaded" warning: quote its real text, say that it comes from the extension's typescriptServerPlugins entry (not from tsconfig.json), that it shows each time VS Code starts until Don't Show Again, and link microsoft/TypeScript#64356. - New "Legacy settings" section: VS Code no longer needs the tsconfig `plugins` entry for @tsrx/typescript-plugin (only other editors do). Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 87b98e2 commit 3466228

1 file changed

Lines changed: 112 additions & 56 deletions

File tree

‎packages/vscode-plugin/README.md‎

Lines changed: 112 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -83,59 +83,115 @@ TypeScript instead of its built-in 7.0.2, which cannot check `.tsrx` files; it
8383
does not find it by itself yet (microsoft/TypeScript#64565). These steps will get
8484
simpler once that is fixed and TypeScript 7.1 is released (tsrx-org/tsrx#991)._
8585

86-
Which compiler serves `.tsrx` files, as tested with the TypeScript 7 extension
87-
1.0.1 and TypeScript `7.1.0-dev.20260930.4`
88-
(`pnpm --filter @tsrx/vscode-plugin test:editor`):
89-
90-
| TypeScript compiler | Who runs it | `.tsrx` files |
91-
| -------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------- |
92-
| 5.9 or 6 | VS Code's built-in TypeScript, TypeScript 7 off | Work (classic backend) |
93-
| 7.1 nightly in the project's `node_modules/typescript` | TypeScript 7 extension, with `js/ts.tsdk.path` set as above | Work (native backend) |
94-
| the same project nightly, without `js/ts.tsdk.path` | TypeScript 7 extension, with its built-in 7.0.2 | Get no TypeScript features, and TSRX's notice says what to set |
95-
| 7.0, including the 7.0.2 built into the TypeScript 7 extension | TypeScript 7 extension | Get no TypeScript features: 7.0 has no content-mapper protocol |
96-
97-
Opening a `.tsrx` file is enough to start TypeScript features, including in
98-
projects with no `.ts` or `.js` source files. TSRX activates Microsoft's
99-
TypeScript extensions and calls `registerContentMappers` when their API supports
100-
it, with `[{ extensions: ['.tsrx'] }]`. That registration discovers the projects
101-
of already-open and subsequently opened `.tsrx` files. The mapper still comes from
102-
each project's `tsconfig.json`; TSRX supplies no inferred-project mapper. Version
103-
selection and any first-run setup follow Microsoft's extensions, just as when
104-
opening a `.ts` file.
105-
106-
With TypeScript 7 enabled in your user settings, its extension shows a one-time
107-
warning that "TypeScript server plugins from the TSRX Syntax for VS Code extension
108-
will not be loaded". That is expected and harmless: the plugin it refers to is the
109-
one VS Code's own tsserver uses for `.tsrx` files on TypeScript 5.9 or 6, and
110-
TypeScript 7 serves them through the content mapper instead. Dismiss it with
111-
**Don't Show Again**.
112-
113-
What differs from the classic backend:
114-
115-
- Closing tags come from the TSRX language server
116-
(`tsrx.autoClosingTags.enabled`): `tsc --lsp` can close tags in `.tsrx` files,
117-
but the TypeScript 7 extension only asks it to in TypeScript and JavaScript
118-
files (upstream microsoft/TypeScript#64564). On classic, VS Code's TypeScript
119-
closes them.
120-
- TSRX compile errors are reported by TypeScript 7 with the `tsrx` source; on
121-
classic the TSRX language server reports them with the `TSRX` source.
122-
- Rename is limited to identifiers whose generated text matches the source
123-
(upstream microsoft/TypeScript#63879).
124-
- Keyword highlights from the TSRX server are not shown while several `.tsrx`
125-
editors are visible side by side (VS Code then only consults the TypeScript 7
126-
extension's multi-document highlight provider).
127-
128-
On both backends, declarations inside `<script>` bodies are type-checked in place
129-
but not listed in the Outline: the body is a block statement in the generated
130-
TypeScript, which TypeScript's navigation tree skips (tsrx-org/tsrx#137).
131-
132-
See the
133-
[`@tsrx/content-mapper` README](https://github.com/tsrx-org/tsrx/tree/main/packages/content-mapper)
134-
for the CLI (`tsc --runExternalCode`), declaration output and known limitations,
135-
its
136-
[`ROLLOUT.md`](https://github.com/tsrx-org/tsrx/blob/main/packages/content-mapper/ROLLOUT.md)
137-
for migration and rollback steps, and its
138-
[`COMPATIBILITY.md`](https://github.com/tsrx-org/tsrx/blob/main/packages/content-mapper/COMPATIBILITY.md)
139-
and
140-
[`BENCHMARKS.md`](https://github.com/tsrx-org/tsrx/blob/main/packages/content-mapper/BENCHMARKS.md)
141-
for how the two backends compare.
86+
### Which TypeScript versions work
87+
88+
This table shows what each TypeScript version does with `.tsrx` files. We tested
89+
it with the TypeScript 7 extension 1.0.1 and TypeScript `7.1.0-dev.20260930.4`. To
90+
run the same tests, use `pnpm --filter @tsrx/vscode-plugin test:editor`.
91+
92+
| TypeScript version | Who runs it | `.tsrx` files |
93+
| -------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
94+
| 5.9 or 6 | VS Code's built-in TypeScript, with TypeScript 7 off | Work (classic backend) |
95+
| 7.1 nightly in the project's `node_modules/typescript` | TypeScript 7 extension, with `js/ts.tsdk.path` set (step 2) | Work (native backend) |
96+
| 7.1 nightly in the project, but `js/ts.tsdk.path` is not set | TypeScript 7 extension, which then uses its built-in 7.0.2 | Get no TypeScript features. A TSRX notice tells you which setting to add. |
97+
| 7.0, including the 7.0.2 built into the TypeScript 7 extension | TypeScript 7 extension | Get no TypeScript features, because TypeScript 7.0 does not support content mappers |
98+
99+
### How TypeScript features start
100+
101+
TypeScript features start when you open a `.tsrx` file. This also works in a
102+
project that has no `.ts` or `.js` files.
103+
104+
When TSRX starts, it does these steps:
105+
106+
1. It activates Microsoft's TypeScript extensions, the same as opening a `.ts`
107+
file does.
108+
2. If an extension's API supports content mappers, TSRX calls
109+
`registerContentMappers` with `[{ extensions: ['.tsrx'] }]`. TypeScript then
110+
finds the project of each `.tsrx` file: the files that are open now and the
111+
files that you open later.
112+
113+
Microsoft's extensions choose the TypeScript version and do any first-run setup,
114+
the same as for a `.ts` file.
115+
116+
The mapper comes only from the `contentMappers` entry in each project's
117+
`tsconfig.json` (step 4). TSRX does not add a mapper for files outside such a
118+
project (TypeScript calls these "inferred projects").
119+
120+
### The "server plugins will not be loaded" warning
121+
122+
If you turn on TypeScript 7 in your user settings, the TypeScript 7 extension
123+
shows this warning:
124+
125+
> TypeScript server plugins from the "TSRX.tsrx-vscode-plugin" extension will not
126+
> be loaded because TypeScript 7 is enabled globally.
127+
128+
You can ignore this warning. The plugin in the warning is
129+
`@tsrx/typescript-plugin`. This extension gives it to VS Code's own TypeScript,
130+
and only the classic backend (TypeScript 5.9 or 6) uses it. TypeScript 7 uses the
131+
content mapper instead.
132+
133+
The warning does not come from a `plugins` entry in your `tsconfig.json`, so
134+
removing that entry does not stop it. The TypeScript 7 extension shows it for each
135+
installed extension that gives a plugin to VS Code's TypeScript. It shows the
136+
warning again each time VS Code starts. To hide it, click **Don't Show Again**. An
137+
extension cannot turn this warning off yet
138+
([microsoft/TypeScript#64356](https://github.com/microsoft/TypeScript/issues/64356)).
139+
140+
### Differences from the classic backend
141+
142+
On the native backend (TypeScript 7):
143+
144+
- **Closing tags:** the TSRX language server closes tags. The setting is
145+
`tsrx.autoClosingTags.enabled`. TypeScript 7 (`tsc --lsp`) can close tags in
146+
`.tsrx` files, but the TypeScript 7 extension asks it to do this only in
147+
TypeScript and JavaScript files
148+
([microsoft/TypeScript#64564](https://github.com/microsoft/TypeScript/issues/64564)).
149+
On the classic backend, VS Code's TypeScript closes tags.
150+
- **Compile errors:** TypeScript 7 reports TSRX compile errors, with the source
151+
`tsrx`. On the classic backend, the TSRX language server reports them, with the
152+
source `TSRX`.
153+
- **Rename:** you can rename an identifier only if the generated TypeScript has
154+
the same text for it as the `.tsrx` source
155+
([microsoft/TypeScript#63879](https://github.com/microsoft/TypeScript/issues/63879)).
156+
- **Keyword highlights:** when two or more `.tsrx` editors show side by side, the
157+
keyword highlights from the TSRX language server do not show. In this case, VS
158+
Code uses only the multi-document highlight provider of the TypeScript 7
159+
extension.
160+
161+
### Known limitation on both backends
162+
163+
TypeScript checks the declarations inside `<script>` bodies, but the Outline does
164+
not list them. The reason is that the generated TypeScript puts each body in a
165+
block statement, and TypeScript's navigation tree skips block statements
166+
([tsrx-org/tsrx#137](https://github.com/tsrx-org/tsrx/issues/137)).
167+
168+
### More about the content mapper
169+
170+
- [`@tsrx/content-mapper` README](https://github.com/tsrx-org/tsrx/tree/main/packages/content-mapper):
171+
the CLI (`tsc --runExternalCode`), declaration output, and known limitations
172+
- [`ROLLOUT.md`](https://github.com/tsrx-org/tsrx/blob/main/packages/content-mapper/ROLLOUT.md):
173+
migration and rollback steps
174+
- [`COMPATIBILITY.md`](https://github.com/tsrx-org/tsrx/blob/main/packages/content-mapper/COMPATIBILITY.md)
175+
and
176+
[`BENCHMARKS.md`](https://github.com/tsrx-org/tsrx/blob/main/packages/content-mapper/BENCHMARKS.md):
177+
how the two backends compare
178+
179+
## Legacy settings
180+
181+
### tsconfig `plugins` entry
182+
183+
Older versions of this extension needed this entry in `tsconfig.json`, so that
184+
`.ts` and `.tsrx` files could import each other:
185+
186+
```jsonc
187+
{
188+
"compilerOptions": {
189+
"plugins": [{ "name": "@tsrx/typescript-plugin" }],
190+
},
191+
}
192+
```
193+
194+
VS Code no longer needs it (only other editors do). On TypeScript 5.9 or 6, this
195+
extension gives the plugin to VS Code's TypeScript. TypeScript 7 ignores `plugins`
196+
and uses the `contentMappers` entry instead (see
197+
[Native backend setup](#native-backend-setup)).

0 commit comments

Comments
 (0)