Performance

Overview

Fumadocs MDX is a bundler plugin, in other words, it has a higher performance bottleneck. With bundlers like Webpack and Turbopack, it is enough for large docs sites with nearly 500+ MDX files, which is sufficient for almost all use cases.

Since Fumadocs MDX works with your bundler, you can import any files including client components in your MDX files. This allows high flexibility and ensures everything is optimized by default.

Image Optimization

Fumadocs MDX resolves images into static imports with Remark Image. Therefore, your images will be optimized automatically for your React framework (e.g. Next.js Image API).

![Hello](./hello.png)

or in public folder

![Hello](/hello.png)

Yields:

import HelloImage from './hello.png';

<img alt="Hello" src={HelloImage} />

Caveats

Although Fumadocs MDX can handle nearly 500+ files, it could be slow and inefficient. A huge amount of MDX files can cause extremely high memory usage during build and development mode.

This is because of:

• Bundlers do a lot of work under the hood to bundle MDX and JavaScript files and optimize performance.
• Bundlers are not supposed to compile hundreds of MDX files.

Solutions

The main solution is to make the compilation on-demand, such that content is only loaded when it's being requested.

Remote Source

Create your custom content source with remoting content loading.

You can ensure your custom source doesn't need to pre-compile content files, it can process them on-demand with SSG which can improve your build speed. However, you cannot leverage bulid time optimizations (e.g. bundling).

See Custom Source for implementing custom sources.

Lazy Loading

See Lazy Loading.