Skip to Content
🎉 Nextra 4.0 is released. dimaMachina is looking for a new job or consulting .

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