Thursday, August 18, 2022 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).

GitHub: github.com/wooorm
Web: wooorm.com

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.

GitHub: https://github.com/rehypejs/rehype-slug
npm: https://www.npmjs.com/package/rehype-slug

rehype-autolink-headings

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!