Should I use evaluate on the client to render statically served MDX? (v2)

[nimobeeren]

I'm building a docs site with Next.js, and I want to statically generate as much as possible. The site will contain a number of pages with MDX content. All pages will have a shared layout that contains a nav with links to all pages that exist. Seems like a common use-case to me.

I'm looking at different ways of doing this:

@next/mdx

This uses a Webpack loader to transform .mdx files into pages that are served directly. It seems like it's also possible to use a shared layout, using <MDXProvider components={{wrapper: MySharedLayout}} />. Problem here is that MySharedLayout is a regular component, not a page. This means I can't statically generate the list of pages using Next's getStaticProps. Hence I don't think I can use this.

next-mdx-remote

Does not support MDX v2 yet. I want to use MDX v2 because one of the remark plugins I use depends on the micromark parser, which I don't think is available when using MDX v1.

{evaluate} from @mdx-js/mdx

What I'm imagining is to use getStaticProps to fetch the raw MDX text, then on the client pass that to evaluate and render the result. However, I'm struggling to make this work, even given a hardcoded string for the raw MDX. I'm more than happy to provide details, but from reading the docs and experimenting, it just doesn't seem like the way MDX is supposed to work.

---

Does anyone have a similar use-case and willing to share their solution? Or perhaps some general knowledge of MDX that you think might help to understand the problem better? Please let me know! 🙏

[wooorm]

Hi Nimo!

As you mention evaluate, which is a (very nice, IMO) v2 feature, I’d recommend not using @next/mdx now, as it is on v1. If you have the chance and working on something new, I’d recommend starting with MDX 2.

The folks from next-mdx-remote are working on MDX v2 support. It’s not there yet.

I think what you’re looking for is pre-compiling MDX on the server and running it on the client. Tools like mdx-bundler can do that. It’s also something that React Server Components (RSC) does, which is used on the v2 website, but extremely experimental, though I’m mentioning it here because it will solve some of what you’re currently trying to solve.

Based on your last idea, I’d say: A different solution, with just xdm/MDX 2, is to compile to outputFormat: 'function-body' on the server, and run the code on the client. evaluate does both steps in one go.
If you split these two lines, with the compile part on the server, and the run part on the client, you could make this work.

More on outputFormat is documented here: https://v2.mdxjs.com/packages/mdx/#optionsoutputformat

[nimobeeren]

Hey Titus!

Thank you so much, your response was incredibly helpful in figuring out a direction to go. I went with the compile and run approach. It worked quite well, you can check out the code here if you like.

Next thing is getting import to work (looking at useDynamicImport).

Thanks again! 🤗

[nimobeeren]

Actually, I'm curious why run and runSync are not exported from @mdx-js/mdx? It would be nice to have that available to consumers.

[nimobeeren]

By the way, I think @next/mdx does work with MDX v2, it doesn't have a direct dependency on MDX packages, it just lists them as peer dependencies. I tried it and it seemed to work fine. I'm pretty sure it was indeed using v2 packages, because I had to set providerImportSource (a v2 addition) to make it work with <MDXProvider components={...}>.

[wooorm]

Good points about run. See #1792 as well.

And glad to hear next/mdx works!

[xHomu]

I'm sticking with next-mdx-remote for a similar use case.

While the remote library hasn't fully caught up yet, most plugins does somehow work if you ask typescript nicely to simply ignore typing errors for now:

  const mdxSource = await serialize(source.mdx, {
    mdxOptions: {
      
    //temporary fix
    // @ts-ignore: Unreachable code error
      remarkPlugins: [remarkGfm],
      
    //temporary fix
    // @ts-ignore: Unreachable code error
      rehypePlugins: [rehypeSanitize],
    }
  }) 

The syntax differences between v1 and v2 aren't that different enough to completely break things yet.

This builds and compile fine on my current iteration on NextJS v12:

    "@mdx-js/mdx": "^2.0.0-rc.1",
    "@mdx-js/react": "^2.0.0-rc.1",
    "next": "^12.0.1",
    "next-mdx-remote": "^3.0.5",
    "rehype-sanitize": "^5.0.0",
    "remark-gfm": "^3.0.1",