Support remark/rehype/recma transformer plugins

[remcohaszing]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

Currentle the language service only supports unified plugins that register micromark syntax extensions. It doesn’t support transformer plugins yet.

For example, remark-mdx-frontmatter, rehype-mdx-title, and recma-nextjs-static-props provide a transformers that injects ESM exports into the AST.

Solution

TypeScript needs to be aware of injected variables and their types. I don’t know how yet.

Alternatives

🤷

[remcohaszing]

I have some vague ideas, but none of these are ideal.

Firstly, let’s determine what it means for IntelliSense to apply a transformer.

Transformers can:

1. Inject module level exports, which become available everywhere. (rehype-mdx-title, remark-mdx-frontmatter)
2. Inject variables into _createMdxContent, which become available inside JSX and expressions.
3. Give meaning to custom constructs (rehype-mdx-code-props, remark-mdx-math-enhanced).

Most transformers transform the hast in ways that doesn’t affect the editor experience. For example remark-toc injects a table of contents, but that doesn’t introduce variables nor remove anything relevant.

Some potential solutions:

1. If custom plugins are defined, we can run all plugins, compiling to ESTree. We can then detect generated variable declarations and insert them into the virtual code.
   • Maybe we could even support expressions and JSX expressions if they have positional data and for example their value is an empty string?
   • Types now depends entirely on inference.
2. Plugins could have a custom entrypoint for MDX analyzer, then use a special API to resolve types.
   • We need to define what that API is.
   • Custom logic is needed for a plugin to support IntelliSense.
   • Plugins have control to make types more specific.
3. Add hardcoded support for a selective list of plugins.
   • Probably best support for these specific plugins.
   • Not pluggable.

[ezzatron]

I ran into the issue described in #445 (except that I use meta as the variable instead of frontmatter) and thought maybe it could be worked around with a global type declaration like:

// mdx.d.ts
declare global {
  var meta: any;
}

But unfortunately that doesn't work. Is there a chance we could get support for something similar to the MDXProvidedComponents type that we can extend to define what globals are available in MDX files?

[remcohaszing]

Hi Erin! Thanks for thinking with us on a solution. I like your idea, but sadly it won’t work. Firstly, declare global has special meaning in TypeScript. We can use MDXProvidedComponents, because we know what name to look for. So we might consider something like:

declare global {
  interface MDXGlobals {
    meta: MyFrontmatterType
  }
}

Probably even nicer would be:

declare module '*.mdx' {
  declare const meta: MyFrontmatterType
}

However, this won’t work either. At the moment we transform the MDX into a virtual file, we do not have any type information.

Maybe we should just add hardcoded support for well-known plugins.

[ezzatron]

Thanks for the explanation. Can't say that I fully understand all the moving parts, but I can definitely appreciate that it's a challenging thing to support!

[remcohaszing]

Given the following config:

{
  "mdx": {
    "plugins": [
      ["remark-mdx-frontmatter", { "name": "someName" }]
    ]
  }
}

and the following input:

---
Hello: frontmatter
---

It could be possible to generate virtual code like this:

/** @satisfies {typeof import('*.mdx').someName} */
export const someName = {
  "Hello": "frontmatter"
}

This virtual code can contain mappings to the original code.

The result would be support for validation, and probably also completion etc for YAML frontmatter. This would then match the types used for *.mdx files that tsc actually uses, so there’s some additional type safety in that regard as well.