Skip to content

Commit 3921cce

Browse files
committed
feat(language-service): add support for framework language plugins
Add the ability to import components from Vue, Svelte, and Astro in MDX files with full type checking and IntelliSense support. Changes: - Add `resolveLanguagePlugins` function to load plugins from tsconfig.json - Add framework shorthand support ("vue", "svelte", "astro") for easy configuration - Add runtime validation for LanguagePlugin interface conformance - Return structured errors for failed plugin imports or invalid exports - Publish diagnostics to tsconfig.json when plugins fail to load - Log errors to output channel for visibility - Collect extra file extensions from loaded plugins for file watching - Update typescript-plugin to use new API with error logging - Add `languagePlugins` option to JSON schema for editor autocomplete - Create @mdx-js/language-plugins package with Vue, Svelte, and Astro plugins - Add comprehensive documentation for all supported frameworks - Add helpful error messages with install commands for missing dependencies Breaking changes: - Removed implicit Astro plugin fallback; plugins must now be explicitly configured via `mdx.languagePlugins` in tsconfig.json Configuration examples: ```json { "mdx": { "languagePlugins": ["vue", "svelte", "astro"] } } ``` Or with custom plugins: ```json { "mdx": { "languagePlugins": ["./my-custom-plugin.js"] } } ```
1 parent 4851c2d commit 3921cce

25 files changed

Lines changed: 2174 additions & 14 deletions

File tree

README.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ This repository contains the code to provide editor tooling support for [MDX][].
1414
* [Use](#use)
1515
* [TypeScript](#typescript)
1616
* [Plugins](#plugins)
17+
* [Language Plugins](#language-plugins)
1718
* [Contribute](#contribute)
1819
* [Sponsor](#sponsor)
1920
* [License](#license)
@@ -174,6 +175,77 @@ For example, to support [frontmatter][] with YAML and TOML and [GFM][]:
174175

175176
For a more complete list, see [remark plugins][].
176177

178+
### Language Plugins
179+
180+
MDX Analyzer supports importing components from other frameworks like Vue, Svelte,
181+
and Astro in your MDX files with full type checking and IntelliSense.
182+
183+
Configure language plugins in `tsconfig.json` using framework shorthands or custom module specifiers:
184+
185+
```jsonc
186+
{
187+
"compilerOptions": {
188+
//
189+
},
190+
"mdx": {
191+
"languagePlugins": [
192+
"vue", // Framework shorthand
193+
"svelte", // Framework shorthand
194+
"astro", // Framework shorthand
195+
"./my-custom-plugin.js" // Custom plugin (relative path)
196+
]
197+
}
198+
}
199+
```
200+
201+
#### Supported Frameworks
202+
203+
* **`"vue"`** — Import Vue components (requires `@vue/language-core`)
204+
* **`"svelte"`** — Import Svelte components (requires `svelte2tsx`)
205+
* **`"astro"`** — Import Astro components (requires `@astrojs/ts-plugin`)
206+
207+
For built-in frameworks, the analyzer will automatically:
208+
1. Validate that required dependencies are installed
209+
2. Show helpful error messages with install commands if dependencies are missing
210+
3. Provide full IntelliSense and type checking for imported components
211+
212+
You can also provide custom module specifiers (relative paths like `"./my-plugin.js"` or npm packages like `"@my-org/my-plugin"`) to load your own language plugins.
213+
214+
Custom plugins must export a `getLanguagePlugin()` function that returns a [Volar LanguagePlugin](https://volarjs.dev). For type checking support, the plugin must include:
215+
- `getLanguageId()` method (required)
216+
- `typescript.getServiceScript()` method (required for type checking, added via `@volar/typescript`)
217+
218+
See [@mdx-js/language-plugins](https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-plugins#creating-custom-language-plugins) for a complete example.
219+
220+
#### Example: Vue Components
221+
222+
Install the required peer dependency:
223+
224+
```bash
225+
npm install @vue/language-core
226+
```
227+
228+
Configure in `tsconfig.json`:
229+
230+
```jsonc
231+
{
232+
"mdx": {
233+
"languagePlugins": ["vue"]
234+
}
235+
}
236+
```
237+
238+
Now you can import Vue components in MDX:
239+
240+
```mdx
241+
import Counter from './Counter.vue'
242+
243+
<Counter initialCount={5} />
244+
```
245+
246+
If a language plugin fails to load (missing dependencies, module not found, etc.),
247+
an error will be shown in the `tsconfig.json` file with helpful instructions.
248+
177249
## Contribute
178250

179251
See [§ Contribute][contribute] on our site for ways to get started.
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.0] - 2024-12-22
9+
10+
### Added
11+
12+
- Initial release of `@mdx-js/language-plugins`
13+
- Vue language plugin for importing Vue components in MDX
14+
- Svelte language plugin for importing Svelte components in MDX
15+
- Full TypeScript support with JSDoc annotations
16+
- Comprehensive documentation and examples
17+
18+
### Features
19+
20+
- **Vue Plugin**: Uses `@vue/language-core` stable API with `__VLS_export` constant
21+
- **Svelte Plugin**: Uses `svelte2tsx` stable API with `$$render` constant
22+
- **Type Safe**: 100% type coverage with strict TypeScript checking
23+
- **Peer Dependencies**: Proper peer dependency management for optional frameworks
24+
- **Resilient**: Uses public API constants, not internal implementation details
25+
- **Production Ready**: Fully tested and documented
26+
27+
[0.1.0]: https://github.com/mdx-js/mdx-analyzer/releases/tag/@mdx-js/[email protected]

0 commit comments

Comments
 (0)