From 63fd208d53f13e5b2451c9f9bc1b7fd136d22c71 Mon Sep 17 00:00:00 2001
From: Remco Haszing <remcohaszing@gmail.com>
Date: Sun, 15 May 2022 19:03:31 +0200
Subject: [PATCH] Add `@next/mdx` to Next.js getting started guide

Closes GH-2040.

Reviewed-by: Titus Wormer <tituswormer@gmail.com>
---
 docs/docs/getting-started.server.mdx | 87 +++++++++++++++++++---------
 1 file changed, 60 insertions(+), 27 deletions(-)

diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx
index 35681f2de..1d3b9afdb 100644
--- a/docs/docs/getting-started.server.mdx
+++ b/docs/docs/getting-started.server.mdx
@@ -549,7 +549,7 @@ the loader to the webpack config, by rewiring `react-scripts` using
 
 <Note type="info">
   **Note**: warnings about CRACO having `incorrect peer dependency
-    "react-scripts@^4.0.0"` can be ignored for the above to work.
+        "react-scripts@^4.0.0"` can be ignored for the above to work.
 </Note>
 
 See also [¶ Webpack][webpack], which is used in CRA, and see [¶ React][react],
@@ -573,40 +573,67 @@ on how to use MDX with Gatsby.
   <summary>Expand example</summary>
 
   ```js path="next.config.js"
-  module.exports = {
-    // Prefer loading of ES Modules over CommonJS
-    experimental: {esmExternals: true},
+  import nextMDX from '@next/mdx'
+
+  const withMDX = nextMDX({
+    // By default only the .mdx extension is supported.
+    extension: /\.mdx?$/,
+    options: {/* providerImportSource: …, otherOptions… */}
+  })
+
+  export default withMDX({
     // Support MDX files as pages:
     pageExtensions: ['md', 'mdx', 'tsx', 'ts', 'jsx', 'js'],
-    // Support loading `.md`, `.mdx`:
-    webpack(config, options) {
-      config.module.rules.push({
-        test: /\.mdx?$/,
-        use: [
-          // The default `babel-loader` used by Next:
-          options.defaultLoaders.babel,
-          {
-            loader: '@mdx-js/loader',
-            /** @type {import('@mdx-js/loader').Options} */
-            options: {/* jsxImportSource: …, otherOptions… */}
-          }
-        ]
-      })
-
-      return config
-    }
-  }
+  })
   ```
 </details>
 
-[Next](https://nextjs.org) supports webpack loaders by overwriting the webpack
-config in `next.config.js`.
+[Next.js](https://nextjs.org) has its own package to support MDX.
 
-Install and configure the webpack loader [`@mdx-js/loader`][webpack].
+Install and configure [`@next/mdx`][@next/mdx].
 There is no need to configure your JSX runtime as React is already set up.
 
-See also [¶ Webpack][webpack] and [¶ React][react], which you’re using, for
-more on those tools.
+The MDX provider can be configured in [`pages/_app.js`][next-app].
+In order to use it, you need to configure the `providerImportSource` as
+well.
+
+<details>
+  <summary>Expand example</summary>
+
+  ```js path="next.config.js"
+  import nextMDX from '@next/mdx'
+
+  const withMDX = nextMDX({
+    // By default only the .mdx extension is supported.
+    extension: /\.mdx?$/,
+    options: {providerImportSource: '@mdx-js/react',  /* otherOptions… */}
+  })
+
+  export default withMDX({
+    // Support MDX files as pages:
+    pageExtensions: ['md', 'mdx', 'tsx', 'ts', 'jsx', 'js'],
+  })
+  ```
+
+  ```jsx path="pages/_app.js"
+  import {MDXProvider} from '@mdx-js/react'
+  import {Header} from '../components/Header.js'
+
+  const components = {
+    h1: Header
+  }
+
+  export default function App({Component, pageProps}) {
+    return (
+      <MDXProvider components={components}>
+        <Component {...pageProps} />
+      </MDXProvider>
+    )
+  }
+  ```
+</details>
+
+See [Using MDX with Next.js][next-mdx] for more details.
 
 #### Parcel
 
@@ -842,6 +869,8 @@ See their readmes on how to configure them.
 *   If you’re getting errors integrating MDX, see
     [§ Troubleshooting MDX][trouble] or [§ Support][support]
 
+[@next/mdx]: https://github.com/vercel/next.js/tree/canary/packages/next-mdx
+
 [svelte-jsx]: https://github.com/kenoxa/svelte-jsx
 
 [jsx]: #jsx
@@ -874,6 +903,10 @@ See their readmes on how to configure them.
 
 [mdx-vue]: /packages/vue/
 
+[next-app]: https://nextjs.org/docs/advanced-features/custom-app
+
+[next-mdx]: https://nextjs.org/docs/advanced-features/using-mdx
+
 [evaluate]: /packages/mdx/#evaluatefile-options
 
 [options-jsximportsource]: /packages/mdx/#optionsjsximportsource