Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add @next/mdx to Next.js getting started guide #2040

Merged
merged 9 commits into from May 15, 2022
88 changes: 61 additions & 27 deletions docs/docs/getting-started.server.mdx
Expand Up @@ -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],
Expand All @@ -573,40 +573,68 @@ 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({
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe Next itself, on pages, asks to first assign to a const, and the export default, so that there’s a name attached.
Should we do the same, or is it fine?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don’t really understand what you mean, but this syntax is very similar to this paragraph on using MDX.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe there’s a warning in Next.js for:

export default () => {}

It wants you to assign to a name:

const SomePage = () => {}
export default SomePage

That is to attach a name. I think that’s good here too.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn’t a page, it’s the configuration file (next.config.js).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand it is not a page.
I use Next.js recommendation as an example.
It is still good to name things.
My assumption is that errors will occur and a name will improve stack traces.

// 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].
remcohaszing marked this conversation as resolved.
Show resolved Hide resolved
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… */}
remcohaszing marked this conversation as resolved.
Show resolved Hide resolved
})

export default withMDX({
// Support MDX files as pages:
pageExtensions: ['md', 'mdx', 'tsx', 'ts', 'jsx', 'js'],
})
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it needed to repeat this? Maybe With the same `next.config.js` as above?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It’s different. It includes the providerImportSource option.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps a diff would be clearer, to focus on only adding the provider import source?
Not adamant about this, go with what you want.


```jsx path="pages/_app.js"
import {MDXProvider} from '@mdx-js/react'

import {Header} from '../components/Header'
remcohaszing marked this conversation as resolved.
Show resolved Hide resolved

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.
remcohaszing marked this conversation as resolved.
Show resolved Hide resolved

#### Parcel

Expand Down Expand Up @@ -842,6 +870,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
remcohaszing marked this conversation as resolved.
Show resolved Hide resolved

[svelte-jsx]: https://github.com/kenoxa/svelte-jsx

[jsx]: #jsx
Expand Down Expand Up @@ -874,6 +904,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
Expand Down