How to add custom component mapping with @mdx-js/loader?

[joulev]

I use Next.js so I have a loader like this

webpack: (config, options) => {
  config.module.rules.push({
    test: /\.mdx$/, // no need of .md
    use: [
      options.defaultLoaders.babel,
      {
        loader: "@mdx-js/loader",
        /** @type {import("@mdx-js/loader").Options} */
        options: {},
      },
    ],
  });
  return config;
}

Now I can use MDX files directly as pages just fine.

// pages/hello.mdx
// Now I can access it at `/hello`

# Hello world!

However, I want to override, say, <h1> elements with my own <Heading>, something exactly like custom components mapping.

I think I have missed some documentation section here, but I can't find out or figure out myself how to do that with just a MDX file and the above webpack configuration alone.

How should I do that?

[wooorm]

I don’t understand what you’re asking for. You want to have React components in your webpack config? That’s not where React components go.

You found the docs for “custom components mapping” already. The page continues by explaining the optional MDX provider. That are the two ways to do this. There are no other ways.

[joulev]

I don’t understand what you’re asking for. You want to have React components in your webpack config? That’s not where React components go.

I'm trying to use MDX files directly as pages, as described here (@next/mdx is essentially a wrapper of @mdx-js/loader). So MDX files are used directly to render HTML instead of imported to a different JSX file.

There are no other ways.

Oh I see... so unless I use the MDX file as a React component imported into another React file, that is apparently impossible. Thank you for your answers.

[wooorm]

I listed two ways: you can use the provider.

[remcohaszing]

MDX components can be injected in Next.js in two ways. Both involve editing pages/_app.js.

1. You can inject the components prop into all of your pages. This will make the prop available in all of your pages, including non MDX pages, but not components defined outside of pages.

   // pages/_app.tsx
   import { Heading } from '../components/Heading'
   import { MDXComponents } from 'mdx/types'
   import { AppProps } from 'next/app'
   
   const components: MDXComponents = {
     h1: Heading
   }
   
   export default function App({ Component, pageProps }: AppProps) {
     return <Component {...pageProps} components={components} />
   }

2. You can insert a @mdx-js/react provider and set it as the providerImportSource. This will make all of your MDX files use your custom components, and won’t inject the components prop inside your non MDX pages.

   // pages/_app.tsx
   import { MDXProvider } from '@mdx-js/react'
   import { MDXComponents } from 'mdx/types'
   import { AppProps } from 'next/app'
   
   import { Heading } from '../components/Heading'
   
   const components: MDXComponents = {
     h1: Heading
   }
   
   export default function App({ Component, pageProps }: AppProps) {
     return (
       <MDXProvider components={components}>
         <Component {...pageProps} />
       </MDXProvider>
     )
   }

   // next.config.js
   import nextMDX from '@next/mdx'
   
   const withMDX = nextMDX({
     options: {
       providerImportSource: '@mdx-js/react'
     }
   })
   
   export default withMDX({
     pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'mdx']
   })

I think typically you’ll want to use the second method.

[joulev]

Thanks, I will try this as soon as I can!

[karlhorky]

With the App Router and mdx-components.tsx, it appears that the second method of setting providerImportSource is no longer working / recommended for Next.js:

• Docs: providerImportSource in MDX is misleading vercel/next.js#54212 (comment)
• Remove unsupported providerImportSource option vercel/next.js#69609

Would be great to still be able to use multiple nested MDXProviders in different app areas, also with the advent of Next.js App Router and mdx-components.tsx:

• Using MDXProvider with mdx-components.tsx vercel/next.js#69613