Skip to Content
🎉 Nextra 4.0 is released. dimaMachina is looking for a new job or consulting .
DocumentationFile Conventionsmdx-components.js

mdx-components.js File

The mdx-components file is required, you use it to customize styles via useMDXComponents function.

Example

The mdx-components.js file must export a single function named useMDXComponents.

mdx-components.js
import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs' // nextra-theme-blog or your custom theme
 
// Get the default MDX components
const themeComponents = getThemeComponents()
 
// Merge components
export function useMDXComponents(components) {
  return {
    ...themeComponents,
    ...components
  }
}

Errors

Module not found: Can’t resolve 'next-mdx-import-source-file'

To fix this, update the turbopack.resolveAlias section in your next.config file:

Note
  • If you’re using Next.js < 15.3, use experimental.turbopack.resolveAlias
  • If you’re using Next.js ≥ 15.3, use turbopack.resolveAlias
next.config.mjs
import nextra from 'nextra'
 
const withNextra = nextra()
 
export default withNextra({
+ turbopack: {
+   resolveAlias: {
+     // Path to your `mdx-components` file with extension
+     'next-mdx-import-source-file': './src/mdx-components.tsx'
+   }
+ }
})
Tip
  • You can keep mdx-components file in root of your project, or in src directory.
  • The .js, .jsx, or .tsx file extensions can be used for mdx-components file.
  • When importing useMDXComponents, alias it as getMDXComponents to avoid a false positive error from the ESLint React Hooks plugin.
react-hooks/rules-of-hooks
React Hook "useMDXComponents" cannot be called at the top level.
React Hooks must be called in a React function component or a custom React Hook function.
Last updated on
_meta.jscontent