Repository: vercel/next.js
Pull request: Update MDX documentation to use next-mdx-remote-client

From what I understand, this is the latest recommendations. I've gotten issues with `next-mdx-remote` recently.

Changed files:
filename: docs/01-app/02-guides/mdx.mdx
patch: @@ -58,7 +58,19 @@ const withMDX = createMDX({
 export default withMDX(nextConfig)
 ```
 
-This allows `.md` and `.mdx` files to act as pages, routes, or imports in your application.
+This allows `.mdx` files to act as pages, routes, or imports in your application.
+
+### Handling `.md` files
+
+By default, `next/mdx` only compiles files with the `.mdx` extension. To handle `.md` files with webpack, update the `extension` option:
+
+```js filename="next.config.mjs"
+const withMDX = createMDX({
+  extension: /\.(md|mdx)$/,
+})
+```
+
+> **Good to know**: [Turbopack](/docs/app/api-reference/turbopack) does not currently support the `extension` option and therefore does not support `.md` files.
 
 ## Add an `mdx-components.tsx` file
 
@@ -731,16 +743,16 @@ export default withMDX(nextConfig)
 
 ## Remote MDX
 
-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 CMS, database, or anywhere else. A popular community package for this use is [`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote#react-server-components-rsc--nextjs-app-directory-support).
+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 CMS, database, or anywhere else. A community package for this use is [`next-mdx-remote-client`](https://github.com/ipikuka/next-mdx-remote-client?tab=readme-ov-file#the-part-associated-with-nextjs-app-router).
 
 > **Good to know**: Please proceed with caution. MDX compiles to JavaScript and is executed on the server. You should only fetch MDX content from a trusted source, otherwise this can lead to remote code execution (RCE).
 
-The following example uses `next-mdx-remote`:
+The following example uses `next-mdx-remote-client`:
 
 <AppOnly>
 
 ```tsx filename="app/mdx-page-remote/page.tsx" switcher
-import { MDXRemote } from 'next-mdx-remote/rsc'
+import { MDXRemote } from 'next-mdx-remote-client/rsc'
 
 export default async function RemoteMdxPage() {
   // MDX text - can be from a database, CMS, fetch, anywhere...
@@ -751,7 +763,7 @@ export default async function RemoteMdxPage() {
 ```
 
 ```jsx filename="app/mdx-page-remote/page.js" switcher
-import { MDXRemote } from 'next-mdx-remote/rsc'
+import { MDXRemote } from 'next-mdx-remote-client/rsc'
 
 export default async function RemoteMdxPage() {
   // MDX text - can be from a database, CMS, fetch, anywhere...
@@ -766,39 +778,48 @@ export default async function RemoteMdxPage() {
 <PagesOnly>
 
 ```tsx filename="pages/mdx-page-remote.tsx" switcher
-import { serialize } from 'next-mdx-remote/serialize'
-import { MDXRemote, MDXRemoteSerializeResult } from 'next-mdx-remote'
+import {
+  serialize,
+  type SerializeResult,
+} from 'next-mdx-remote-client/serialize'
+import { MDXClient } from 'next-mdx-remote-client'
 
-interface Props {
-  mdxSource: MDXRemoteSerializeResult
+type Props = {
+  mdxSource: SerializeResult
 }
 
 export default function RemoteMdxPage({ mdxSource }: Props) {
-  return <MDXRemote {...mdxSource} />
+  if ('error' in mdxSource) {
+    // either render error UI or throw `mdxSource.error`
+  }
+  return <MDXClient {...mdxSource} />
 }
 
 export async function getStaticProps() {
   // MDX text - can be from a database, CMS, fetch, anywhere...
   const res = await fetch('https:...')
   const mdxText = await res.text()
-  const mdxSource = await serialize(mdxText)
+  const mdxSource = await serialize({ source: mdxText })
   return { props: { mdxSource } }
 }
 ```
 
 ```jsx filename="pages/mdx-page-remote.js" switcher
-import { serialize } from 'next-mdx-remote/serialize'
-import { MDXRemote } from 'next-mdx-remote'
+import { serialize } from 'next-mdx-remote-client/serialize'
+import { MDXClient } from 'next-mdx-remote-client'
 
 export default function RemoteMdxPage({ mdxSource }) {
-  return <MDXRemote {...mdxSource} />
+  if ('error' in mdxSource) {
+    // either render error UI or throw `mdxSource.error`
+  }
+  return <MDXClient {...mdxSource} />
 }
 
 export async function getStaticProps() {
   // MDX text - can be from a database, CMS, fetch, anywhere...
   const res = await fetch('https:...')
   const mdxText = await res.text()
-  const mdxSource = await serialize(mdxText)
+  const mdxSource = await serialize({ source: mdxText })
   return { props: { mdxSource } }
 }
 ```