--- title: "MDX Configuration Loading" description: "The createMDX process acts as the integration layer between Fumadocs and Next.js. At a high level, this flow initializes the MDX core, manages configuration loading, and prepares the necessary path..." last_updated: "2026-07-02T09:46:39.362674+00:00" canonical_url: "https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/technical/how-it-works/mdx-configuration-loading" ---
Relevant source files The following files were used as context for generating this wiki page: - [packages/mdx/src/next/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/next/index.ts) - [packages/mdx/src/config/load-from-file.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/config/load-from-file.ts) - [packages/mdx/src/core.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/core.ts)
The `createMDX` process acts as the integration layer between Fumadocs and Next.js. At a high level, this flow initializes the MDX core, manages configuration loading, and prepares the necessary paths so that loaders can resolve the compiled MDX configuration during the build or development process. This process is critical for ensuring that MDX files are transformed using the correct project-specific configuration. By dynamically determining the location of the compiled configuration file, the system maintains a seamless link between user-defined `source.config.ts` files and the underlying build tools. ### Step-by-Step Execution #### 1. `createMDX` The entry point `createMDX` is invoked by the user's `next.config.mjs`. It orchestrates the setup of the `Core` instance and checks if the environment needs initialization. If `_FUMADOCS_MDX` is not set, it triggers the `init` function to start the development environment or initial compilation. Sources: [packages/mdx/src/next/index.ts:30-38](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/next/index.ts#L30-L38) #### 2. `init` The `init` function prepares the environment. It defines internal utilities for managing config lifecycle (initial load and reload) and handles the development server instance if the environment is in development mode. Sources: [packages/mdx/src/next/index.ts:124-182](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/next/index.ts#L124-L182) #### 3. `devServer` When in development, `devServer` initializes a file watcher (via `chokidar`) to monitor changes to the configuration file or content collections. It ensures that whenever a user modifies the configuration, the system triggers a reload of the core logic. Sources: [packages/mdx/src/next/index.ts:132-176](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/next/index.ts#L132-L176) #### 4. `initOrReload` This function is called both during startup and on file changes. It executes `core.init` and passes in the loaded configuration, which effectively re-hydrates the application with the latest user settings. Sources: [packages/mdx/src/next/index.ts:125-130](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/next/index.ts#L125-L130) #### 5. `loadConfig` This utility compiles the source configuration file using `esbuild` if requested, and then imports the generated module. It ensures the configuration is ready to be consumed by the plugins and core modules. Sources: [packages/mdx/src/config/load-from-file.ts:35-44](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/config/load-from-file.ts#L35-L44) #### 6. `getCompiledConfigPath` Finally, this method on the `Core` object computes the expected filesystem location of the `source.config.mjs` file. This path is then used by the Webpack loaders to access the compiled configuration variables during the compilation of MDX content. Sources: [packages/mdx/src/core.ts:218-220](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/core.ts#L218-L220) > [!NOTE] > The `getCompiledConfigPath` method does not verify file existence; it merely provides the standard path based on the output directory configuration. ### Sequence Diagram ```mermaid sequenceDiagram participant Index as next/index.ts participant Config as config/load-from-file.ts participant Core as core.ts Index->>Index: createMDX() Index->>Index: init() Index->>Index: initOrReload() Index->>Config: loadConfig() Config->>Core: getCompiledConfigPath() Core-->>Config: return path Config-->>Index: return LoadedConfig ``` Sources: [packages/mdx/src/next/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/next/index.ts) ### Flowchart ```mermaid flowchart TD A[createMDX] --> B[init] B --> C[initOrReload] C --> D[loadConfig] D --> E[getCompiledConfigPath] ``` Sources: [packages/mdx/src/next/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/next/index.ts) ### Key Observations * **Boundary Crossing:** The flow transitions from the `next` package integration layer to the `config` management utilities and finally to the `core` logic layer. * **Failure Handling:** In `compileConfig`, failure to build the configuration file results in an explicit error, preventing further execution with invalid settings. * **Performance:** The configuration loading process uses `Date.now()` as a search param on the import URL (in `loadConfig`) to bust the node module cache, ensuring that hot-reloaded configurations are always current. * **Watcher Logic:** The `devServer` uses `chokidar` to detect configuration changes. It calls `watcher.removeAllListeners()` before restarting to prevent listener leaks during hot reloads. > [!TIP] > If you encounter issues where MDX configuration changes aren't being reflected, ensure that your `outDir` (default `.source`) is not being ignored by your IDE or build cache. > [!WARNING] > Manual editing of the files inside the `.source` directory is discouraged as they are generated by `esbuild` during the `loadConfig` process. ## Sitemap See the full [sitemap](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/llms.txt) for all pages in this wiki.