Async Mode

Introduction

By default, all Markdown and MDX files need to be pre-compiled first. The same constraint also applies to the development server.

This may result in longer dev server start times for large docs sites. You can enable Async Mode on docs collections to improve this.

Setup

Enable Async Mode.

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    async: true,
  },
});

Next.js

Turbopack doesn't support lazy bundling at the moment, Async Mode works by performing on-demand compilation with MDX Remote.

You need to install extra dependencies:

npm i @fumadocs/mdx-remote shiki

Vite

Vite has native support for lazy bundling, you only need to update loader() after enabling it.

import { loader } from 'fumadocs-core/source';
import { docs, create } from '@/.source';

export const source = loader({
  baseUrl: '/docs',
  source: await create.sourceAsync(docs.doc, docs.meta),
  source: await create.sourceLazy(docs.doc, docs.meta),
});

Usage

Frontmatter properties are still available on page object, but you need to invoke the load() async function to load the compiled content (and its exports).

For example:

import { source } from '@/lib/source';
import { getMDXComponents } from '@/mdx-components';

const page = source.getPage(['...']);

if (page) {
  // frontmatter properties are available
  console.log(page.data);

  // Markdown content requires await
  const { body: MdxContent, toc } = await page.data.load();

  console.log(toc);

  return <MdxContent components={getMDXComponents()} />;
}

When using Async Mode, we highly recommend to use third-party services to implement search, which usually have better capability to handle massive amount of content to index.