mintlify-mdx

Mastering Mintlify

Mintlify is a Next.js App Router site that compiles MDX on the server, hydrates in the browser, and serves via Next. This skill covers the parts the docs don't — what the pipeline actually does, where the sandbox sharp edges are, and how to customize around them.

For content writing, read writing/voice and writing/structure in the docs repo. This skill is for engineers building custom components, integrations, or bundling npm packages.

The Pipeline

.mdx file
  → remark parser (@mdx-js/mdx + acorn)
  → remarkMdxInjectSnippets         ← inlines /snippets/*.jsx ASTs
  → estree-util-to-js (findExport)  ← extracts one export at a time
  → next-mdx-remote-client/serialize (function-body mode)
  → Reflect.construct(SyncFunction, keys.concat(compiledSource))
  → component tree → SSR → hydrate

The critical detail: findExport extracts each ExportNamedDeclaration AST subtree in isolation. Sibling imports, sibling const declarations, sibling exports — all dropped from each export's scope.

Hard Constraints (Memorize These)

1. Each named export is evaluated in isolation

Sibling declarations are invisible. This fails:

// FAILS: "ReferenceError: __lib is not defined"
export const __lib = (() => { return { Terminal, useTerminal }; })();
export const Terminal = __lib.Terminal;        // __lib not in scope
export const useTerminal = __lib.useTerminal;  // nor here

Fix: one self-contained IIFE per export, even if it duplicates bytes.

export const Terminal = (() => { /* full body */ return Terminal; })();
export const useTerminal = (() => { /* full body again */ return useTerminal; })();

2. import expressions are rejected

Function-body mode refuses ESM syntax needing module resolution: import(), import.meta.url, export ... from. Error:

Unexpected missing options.baseUrl needed to support "export … from", "import", or "import.meta.url" when generating "function-body"

Fix: drop dynamic imports. Use plain fetch() instead of SDK imports.