Docs: Clarify that first-party @next/mdx also has dynamic import() - not just next-mdx-remote

[karlhorky]

What is the documentation issue?

Since a few months / years, I have encountered articles such as MDX in Next.js - Space Jelly by @colbyfayock which are based on the (incorrect) assumption that @next/mdx cannot pull in content from other sources such as files outside of the app directory:

The trick here though is that to use the official Next.js MDX package, our content needs to be located inside of the app directory, just like any other page file.

But in our example, say we have a content directory in the root of our project with a dump of our MDX, and it’d be tedious, and frankly a bit overwhelming to put that all inside of the app directory with the page filename pattern, we can instead use Next MDX Remote to render our content from where it is.

This is an incorrect assumption, as files outside of the app directory can be pulled in via static imports and dynamic import():

1. static import
   • https://nextjs.org/docs/app/building-your-application/configuring/mdx#using-imports

   • next.js/examples/app-dir-mdx/app/page.tsx

     Line 4 in 3127e86

     import Content from "./message.mdx";

2. dynamic import()
   • Import MDX components dynamically #12151 (comment)
   • @wesbos in Dynamically load Server Components #51016 (reply in thread)

Apart from the aforementioned blog posts, there seems to be a bunch of community confusion on what is possible using @next/mdx:

• MDX support width appDir enabled #47523
• MDX Blog (v14 App router) with `[slug]` path structure. #58575
• Using mdx provider in a server component #50897
• Recommended way to pass an MDX file from `getServerSideProps` as a prop to a component? #47621
• more...

Even the Next.js MDX docs section "Remote MDX" seem to (incorrectly) implicitly indicate that @next/mdx cannot pull in content from other sources such as files outside of the app directory:

If your MDX files or content lives somewhere else, you can fetch it dynamically on the server. This is useful for content stored in a separate local folder, CMS, database, or anywhere else. A popular community package for this use is next-mdx-remote.

@next/mdx can achieve the same things as next-mdx-remote and mdx-bundler and rsc-mdx, without the significant, non-obvious downsides with the alternatives:

• next-mdx-remote/rsc doesn't allow for importing MDX files within MDX files
• mdx-bundler requires complicated manual configuration to share components to imported .mdx files (not to mention pulling in a bunch of extra bundling dependencies and running the bundling outside of the existing webpack / Turbopack bundler config)

cc @manovotny @leerob @wooorm @remcohaszing

Is there any context that might help us understand?

I'm hoping the context is included above. I can add more if needed.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/building-your-application/configuring/mdx

[samcx]

@karlhorky Thank you for sharing your thoughts! I moved this over to discussions because this doesn't necessarily seem like an issue with incorrect information with our documentation.

I'm actually not 100% familiar with all the capabilities with @next/mdx. Did you want to possibly push a :pr: with changes to our MDX docs?

[wesbos]

Yeah I agree - I wasted probably a day on this. Went down the MDX-remote rabbit hole only to find out that images outside the public dir dont work. If we want all the benefits of next - like images - we need to use the baked in next.js approach.

Good docs on how to use it with dynamic content are really needed. It's a bit of a footgun in that webpack is weird with dynamic imports - but that should also be documented as a gotcha. Or at least a better error message when webpack pukes because it's been scanning 600,000 files in node_modules

[samcx]

@karlhorky @wesbos Thanks for the clarification!

I'll take a look into updating our documentation here about dynamic content. :blob_bowing:

[karlhorky]

Amazing, thanks! Feel free to tag me on the PR - happy to give it a review.

[karlhorky]

@samcx there was a discussion on Twitter today about Next.js MDX options, with some missing knowledge that @next/mdx is a possibility for content outside of the app/ directory

• https://x.com/peduarte/status/1845814417839034738

this kind of nerdsniped me and I made a demo repo showing that it's definitely possible to await import() MDX files outside of the app/ directory:

• https://github.com/karlhorky/next-mdx-dynamic-import-demo

Screen.Recording.2024-10-15.at.17.21.50.mov

[lauri865]

This is actually great. Why the docs don't showcase this is very strange indeed. I lost way too much time trying to create reusable templates with next/mdx. One problem remains though – mdxrs doesn't support remark/rehype plugins (no turbo support), and there's been little movements on that front for a while. Good luck doing any templating without frontmatter. Hence we ended up using content collections instead, which works great even with turbo, and offers nice typesafety as a bonus. And we could construct our mdx files in a way which would requires minimal (to no) refactoring in case we do want to host the mdx content remotely at some point.

If instead we would have started exporting metadata from the mdx files as the docs suggest, we would need to refactor every single mdx file in the future when switching to a remote.

At this point I wish next/mdx didn't exist at all, because it just sent us down a rabbit hole of various blockers and incompatibilities.