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.

Sign up for GitHub

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
Merged

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

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7e5b7d6
Enhance the Next.js getting started guide
remcohaszing May 15, 2022
4d847a3
Update docs/docs/getting-started.server.mdx
remcohaszing May 15, 2022
53c814a
Update docs/docs/getting-started.server.mdx
remcohaszing May 15, 2022
f2586e9
Update docs/docs/getting-started.server.mdx
remcohaszing May 15, 2022
c634403
Update docs/docs/getting-started.server.mdx
remcohaszing May 15, 2022
b3b2c09
Use named next-app link
remcohaszing May 15, 2022
2638533
Rename React provider to MDX provider
remcohaszing May 15, 2022
6be23f7
Update docs/docs/getting-started.server.mdx
remcohaszing May 15, 2022
b6dd3a2
Update docs/docs/getting-started.server.mdx
remcohaszing May 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 60 additions & 27 deletions docs/docs/getting-started.server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
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,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({
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… */}
})

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

#### Parcel

Expand Down Expand Up @@ -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
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 +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
Expand Down