Merge packaged theme components with original components

[b-kamphorst]

Hi community 👋

I recently wrote my first docusaurus plugin (npm, github). For now, the essence is that it exports a remark plugin that adds MDX components to some markdown AST trees, and it defines those components in a theme. Unfortunately it turned out that my theme completely overrides the original components so that e.g. admonitions no longer render correctly.

I currently have

 // src/theme/Components.tsx

import GlossaryIndex from "@theme/GlossaryIndex";
import GlossaryTooltip from "@theme/GlossaryTooltip";

export default {
  GlossaryIndex,
  GlossaryTooltip,
};

I realize that the recommended pattern is the following:

import MDXComponents from "@theme-original/MDXComponents";
import GlossaryIndex from "@theme/GlossaryIndex";
import GlossaryTooltip from "@theme/GlossaryTooltip";

export default {
  ...MDXComponents,
  GlossaryIndex,
  GlossaryTooltip,
};

However, if I then build my package and use it in an example project (same repo, npm workspace links to my plugin), I get

Cannot access '__WEBPACK_DEFAULT_EXPORT__' before initialization

I was suggested to not build my package as ES module but as commonJS instead. But removing the "type": "module" from package.json and configuring "module": "commonjs" in tsconfig.json results in the same situation as before where the original components are not loaded. I tried many other approaches but after hours of trying I am completely stuck.

I did manage to make the plugin work by adding an import statement for my component in every markdown AST, see here. But I feel like I had better follow the MDXComponents.tsx approach as it is recommended and it simplified my plugin. All help is appreciated!

Disclaimer: I am very new to npm and typescript and I work on my first docusaurus plugin. I am easily confused by ES modules versus commonJS, and making any sense of package.json and tsconfig.json (incl. compilerOptions). Please bear with me as I do my best to learn 🙏

[slorber]

Hi

The MDXComponents is one global map per site, provided by the classic theme, that implicitly provides "ambient components" available to all rendered MDX documents.

Creating a theme that overrides the default from our classic theme is not a good idea: it creates a coupling point between your theme and the classic theme, and even makes it sensitive to theme ordering issue (@theme-original could be yours, or the classic theme depending on how you configure your theme)

We document it here: https://docusaurus.io/docs/markdown-features/react#mdx-component-scope

However, I don't think it's a good idea in general for a theme to extend another. Keep in mind that if users also create their own MDXComponents, then your version will never be used, and they'll have to register your custom components themselves.

I don't know why you encountered bundling errors, but I'd suggest that you should try to make your theme self-encapsulated, and adding explicit exports for the 2 components is likely a more portable solution. This way it works whether users have a MDXComponents or not.

In general, I'm not satisfied with the @theme and @theme-original system for this reason: it doesn't permit a theme to "enhance" another, or it can only do so once at most, and won't really fully cover the "theme composition" problem using multiple layers.

[b-kamphorst]

Thank you for taking time for this, @slorber.

... I'd suggest that you should try to make your theme self-encapsulated, and adding explicit exports for the 2 components is likely a more portable solution. This way it works whether users have a MDXComponents or not.

That sounds like the best way to go. Just to be clear though: if I export these components, do I still have to manually import them in all relevant .md(x) files/ auto-import them with a remark plugin (my current solution) or is there another (recommended) way to make them globally available?

[slorber]

If the components are in the MDX map, they are automatically available everywhere: MDX docs use them from the React context.

Otherwise, they need to be imported, either manually or automatically.

Here's an example Remark plugin that automatically adds imports to all MDX docs containing npm2yarn code blocks: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-remark-plugin-npm2yarn/src/index.ts

Note: in the future we'd like to introduce an API so that plugins can register remark plugins automatically. For now, you'd have to document in your lib that users need to add the remark plugin manually if they want those components to become ambiantly available

[b-kamphorst]

I have no idea how to add a component to the MDX map, but judging from the plugin that you shared I take it that I will just have to add the imports myself. Which works, so I'll stick to that.

It is a bit of a pity though that I spend hours on the ...MDXComponents approach though. I feel that the docs here can be improved. Then again, I don't feel that I understand this sufficiently to propose a PR to improve the docs here. And I may just be too novice in docusaurus/ React, causing me to misunderstand the docs.

Either way: thank you @slorber, at least I can move on without the "there must be a better way" thought nagging me :)

[slorber]

It's hard for us to document this properly because to be honest we are not yet satisfied with the solutions we offer, so the best currently is likely to ask like you did so that we understand the use case of our community members and can guide them with decent workarounds until we figure out the proper solution