I had run into this problem where my Theme UI theme’s base styles weren’t being applied to the MDX file markup. I thought it was something specific to my site’s configuration so I foolishly spent too much time messing around to validate that and even did the work to upgrade from next-mdx to next-mdx-enhanced.

I won’t make any metaphors about the JS ecosystem and its packages being a house of cards or anything but it turns out that if you have multiple dependencies relying on differring versions of a shared sub depepency you might run into a problem. Now, I was interested in this so I did some digging. Not a ton, but there wasn’t a whole lot of info into what or why that can really be a problem, aside from the obvious that npm packages totally don’t have to adhere to semver. So good luck I guess.

In case you aren’t lucky, like me, this tip might help get you moving.

Firstly, use yarn, it adds a much needed measure of deterministic behavior to your installs. Install yarn.

Then, you’ll want to see if you have any packages dupes. If you have an inkling of the most likely offenders be sure to add the --pattern [term] flag, it’ll limit the number of matches by the term for much easier parsing.

$ yarn list --pattern [term]

Then the neat bit, yarn supports a resolutions key in your package.json file. It allows a project to selectively control depepency resolution - so if there’s a mismatch for a shared depepency you can force a package that you don’t control to use a specific version.

"resolutions": {
    "[package||path||:link||:portal]": "[version override]"
  }

The targeting is pretty flexible too, so be sure to check out the docs.