[Plan] Performance Improvements

[fuma-nama]

What problem will this feature address?

Currently the framework is fast, 161 kb client bundle by default. But it's slower due to:

Fumadocs MDX

No on-demand compilation

On development mode, it should be possible to require compiling MDX pages on-demand, instead of pre-compiling all MDX pages. This is not possible, even on Turbopack, an async import like await import("./file.mdx") will always trigger file.mdx to be bundled first.

However, it is how Fumadocs optimize MDX files - by generating a single file to import all other MDX pages:

export const docs = [toRuntimeAsync({"title":"User Guide","description":"The CLI tool that automates setups and installing components."}, () => import("../content/docs/cli/index.mdx")]

Unused Client Component

MDX pages are compiled into server components via custom loader. For each page, there's different client components being referenced, but Next.js adds all client components into client bundle if they are referenced by a imported server component. This means even if the server component isn't rendered, its client components will still be included in client bundle.

This causes the client components referenced in unused MDX pages loaded by client, while it is unnecessary.

Describe the solution you'd like

• Wait for Turbopack to support on-demand compilation for dynamic imports
• Wait Next.js to support a kind of option that supports detecting referenced client components in a smarter way

Describe alternatives you've considered

N/A

Additional context

No response

[fuma-nama]

we have supported async mode and got it to work on Arktype and our official docs, it's not necessarily better since it also takes time for Next.js bundler to compile packages like mdx-js and for shiki to load, but a big improvement is observered

[fuma-nama]

Async Mode is now stable, feel free to use it if your docs site is getting large.

Also Turbopack will support persistent cache soon, make sure to enable Turbopack for dev server, a big improvement has already observed

[fuma-nama]

Turbopack for production build works for Fumadocs, and a clean production build takes less than 30s for our official site. Minimal site takes less than 10s, with persistent cache I'm sure most performance problems can be solved.

Note that Fumadocs OpenAPI still has problems with Turbopack, we need another breaking change in order to fix that (moving APIPage to fumadocs-openapi/ui instead of fumadocs-openapi/server).