By Paul Scanlon

MDX and ESM rehype Packages

Hey, in this post iā€™m going to show you how to use the latest ESM rehype packages with gatsby-plugin-mdx v3.

Titus Wormer

Before we get started iā€™d like to introduce Titus (@wooorm).

I work most-time on open source maintaining 540+ projects that are downloaded 20B+ times a year. I can spend time as a core team member of unified, building things for content (natural language, markdown, markup) with syntax trees, thanks to the community.

Titus is not only an absolute genius, heā€™s a jolly nice chap too. Heā€™s helped me out more times than I can count. Heā€™s been hugely involved in the upgrading of a number of popular remark and rehype packages. Two of which iā€™ll be discussing in this post.

rehype-slug

This plugin is useful when you have relatively long documents and you want to be able to link to particular sections.

This plugin is useful when you have relatively long documents, where you want users to be able to link to particular sections, and you already have id attributes set on all (or certain?) headings.

The above two packages are quite commonly used in Gatsby sites to enable ā€œclick-ableā€ headings. or ā€œjumplinksā€ in blog posts either written in markdown or MDX. In this post iā€™ll be talking about how to use them with MDX, but the steps are similar for markdown.

Common Installation

The most common way to use these packages with v3 of gatsby-plugin-mdx is as follows.

// gatsby-config.js

module.exports = {
  ...
  plugins: [
    {
      resolve: 'gatsby-plugin-mdx',
      options: {
        rehypePlugins: [require('rehype-slug'), [require('rehype-autolink-headings'), { behavior: 'wrap' }]]
      }
    },
  ]
};

Versions and Errors

The above approach will work when using the following package versions.

// package.json

"gatsby-plugin-mdx": "3.19.0"
"rehype-slug":"4.0.0"
"rehype-autolink-headings":"4.0.0"

After this point both the rehype-slug and rehype-autolink-headings packages were upgraded to ESM only. If you attempt to use versions beyond 4.0.0, youā€™ll likely see the following error when you start up your Gatsby development server.

Error: [ERR_REQUIRE_ESM]: require() of ES Module

Youā€™ll be able to see the changes in both packages if you comb over the commit messages and look for 5.0.0

Using ESM only

Currently gatsby-config.js doesnā€™t support ESM module syntax out of the box, (although, the team are working on it Support ESM usage with Gatsby #31599), but there is a way to use ESM modules with Gatsby.

Hereā€™s how šŸ‘‡.

Upgrade rehype Packages

Upgrade both of the rehype packages to at least 5.0.0, but depending on when youā€™re reading @latest might be a better option.

// package.json

"gatsby-plugin-mdx": "3.19.0"
- "rehype-slug":"4.0.0"
- "rehype-autolink-headings":"4.0.0"
+ "rehype-slug":"5.0.0"
+ "rehype-autolink-headings":"5.0.0"

wrapESMPlugin

Add the following ā€œhelper functionā€ to gatsby-config.js. I lifted this from the Gatsby Docs but, be aware this is a link to the new v4 version of gatsby-plugin-mdx.

I will be writing about the new v4 plugin at some point so stay tuned, or follow me on Twitter for updates: @PaulieScanlon

// gatsby-config.js

const wrapESMPlugin = (name) =>
  function wrapESM(opts) {
    return async (...args) => {
      const mod = await import(name);
      const plugin = mod.default(opts);
      return plugin(...args);
    };
  };

Now, instead of using require, you can use wrapESMPlugin. Hereā€™s the diff.

// gatsby-config.js

module.exports = {
  ...
  plugins: [
    {
      resolve: 'gatsby-plugin-mdx',
      options: {
- rehypePlugins: [require('rehype-slug'), [require('rehype-autolink-headings'), { behavior: 'wrap' }]]
+ rehypePlugins: [wrapESMPlugin('rehype-slug'), [wrapESMPlugin('rehype-autolink-headings'), { behavior: 'wrap' }]]
      }
    },
  ]
};

That should just about wrap things up. I know that this method wonā€™t work for all rehype or remark ESM packages, so if you have attempted to use this approach unsuccessfully, please do drop a comment below and let me know which package and version of that package you were using. Thanks in advance!

Further Reading

As of Aug 17th 2022 Gatsby released v4 of the MDX Plugin. You can read more about how to migrate from v3 to v4 in docs.

Hey!

Leave a reaction and let me know how I'm doing.

  • 0
  • 0
  • 0
  • 0
  • 0
Powered byNeon