Global MDX components do not work when MDX is used via a theme with NPM.

[patrickarlt]

I'm unsure if this is a Gatsby or MDX issue so it is cross posted with MDX mdx-js/mdx#1223

---

Description

I'm running into an issue where we add components to MDX global scope but those components don't render in the page if the theme is installed via NPM, the compnents work fine if the theme is installed via Yarn.

We publish a theme (gatsby-theme-minimal) to a tag on Github via gitpkg. This theme configures MDX via gatsby-plugin-mdx, configures pages and provides a component for rendering MDX files.

Several additional components are added to the <MDXProvider> in the theme:

<MDXProvider components={{ Box, Test }}>
  <MDXRenderer>{mdx.body}</MDXRenderer>
</MDXProvider>

However when we install with npm in the reproduction folder we see this on the /test/ page:

We also see the following message in the console:

Component Box was not imported, exported, or provided by MDXProvider as global scope commons.js line 5071 > Function:14:13
Component Test was not imported, exported, or provided by MDXProvider as global scope commons.js line 5071 > Function:14:13
Component Box was not imported, exported, or provided by MDXProvider as global scope

Installing with yarn in the reproduction folder produces this on the /test/ page:

Steps to reproduce

I have created a minimal reproduction at https://github.com/patrickarlt/gatsby-mdx-theme-reproduction-issue

1. Clone the repo
2. cd reproduction
3. npm install
4. gatsby develop
5. Note the styling on /test/
6. Kill the server
7. gatsby clean
8. Delete package-lock.json and node_modules
9. yarn install
10. gatsby develop
11. Note the styling on /test/

The theme is published via gitpkg to a tag on the reproduction repo.

Actual/Expected result

The MDX page should render the same regardless on installation via Yarn/NPM.

Environment

  System:
    OS: macOS Mojave 10.14.6
    CPU: (8) x64 Intel(R) Core(TM) i7-6820HQ CPU @ 2.70GHz
    Shell: 5.3 - /bin/zsh
  Binaries:
    Node: 12.16.3 - ~/.nvm/versions/node/v12.16.3/bin/node
    Yarn: 1.22.4 - ~/.nvm/versions/node/v12.16.3/bin/yarn
    npm: 6.14.4 - ~/.nvm/versions/node/v12.16.3/bin/npm
  Languages:
    Python: 2.7.10 - /usr/bin/python
  Browsers:
    Chrome: 84.0.4147.125
    Firefox: 80.0
    Safari: 13.1.2
  npmPackages:
    gatsby: ^2.23.12 => 2.24.47
    gatsby-source-filesystem: ^2.1.41 => 2.3.24
    gatsby-theme-minimal: https://github.com/patrickarlt/gatsby-mdx-theme-reproduction-issue.git#gatsby-theme-minimal-v1.0.0-gitpkg => 1.0.0
  npmGlobalPackages:
    gatsby-cli: 2.12.29

[py563]

can confirm i face same issue components are not getting mounted in build on github pages with actions please check build logs on the theme repository Chronoblog/gatsby-theme-chronoblog#56

[mathieudutour]

I have the same issue, I'm pretty sure it's because of different versions of mdx co-living: gatsby uses the pre-release of mdx (2.0.0) while my theme uses 1.x.. The mdx components context is probably not the same (inspecting the renderer shows an empty components context).

[blainekasten]

ccing @laurieontech and @pieh, they might know what's going on here!

[karland]

It is a wild guess, but this seems related: system-ui/theme-ui#1130

I hade a similar issue and fixed it by adding the following to package.json

  "resolutions": {
    "@mdx-js/react": "1.6.16"
  }

My dependencies currently contain:

  "dependencies": {

    "@mdx-js/mdx": "^1.6.16",
    "@mdx-js/react": "^1.6.16",
   
  }

[mathieudutour]

My current workaround is to copy MdxRenderer into my theme to make sure the @mds-js/react is the same.

Here is what is really happening otherwise:

• npm install creates a deps tree like this:

  - gatsby
  - gatsby-plugin-mdx
  - @mdx-js/react@2.0.0
  - your-gatsby-theme
    - @mdx-js/react@1.x
  

• your-gatsby-theme uses MdxProvider from @mdx-js/react and requires the component context from the 1.x version
• your-gatsby-theme uses MdxRenderer from gatsby-plugin-mdx
• gatsby-plugin-mdx requires the component context from the 2.0.0 version because it's its sibling

[py563]

Think that is the use, I will check around in my repository and theme, I just left it like it because I couldn't see the issue only when deploying on GitHub pages. As I tested with my local package-lock.json file and also a yarn-lock file with deployments on render it worked fine so I just pushed a yarn-lock and left to worry about it another day.

[laurieontech]

Thanks for opening the issue! This is in fact a resolution problem related to multiple versions of MDX. It's a problem we're aware of but limited in solving because it's really up to the package manager.

The options are to use yarn instead, not ideal. Or set a resolution for the relevant @mdx-js/mdx and/or @mdx-js/react.

I'm going to close this for now but please let me know if you're still seeing this issue after trying the above.

[mathieudutour]

The issue isn't about us not using yarn, it's about the users of gatsby themes using mdx that are really confused because there is no error showing.

I do think there are solutions:

• having MdxRenderer accept a mdx reference
• exposing MdxProvider in gatsby-plugin-mdx

Both would make sure only one mdx version is used.

I don't think this issue should be closed like this. It's a pretty big deal, especially since mdx@2 isn't released yet.

[laurieontech]

You're absolutely right that it's a papercut in its current state. The best solution may be to prevent the version of MDX that comes with gatsby now from being used/potentially clashing. The PR I've opened should be sufficient.

[patrickarlt]

I also managed to resolve this by making @mdx-js/react and @mdx-js/mdx peerDependencies of my theme instead of dependencies. Then in any Gatsby project that includes the theme yo uneed to put @mdx-js/mdx and @mdx-js/react as dependencies alongside the theme. This causes npm to install them at the root of node_modules and everything seems to work. I still think #26660 is a good PR and should probally be included to permanently resolve this since there are lot of themes that probably have a direct dependency on @mdx-js/mdx and @mdx-js/react.