Architecting MDX Rendering: Compilation vs. Runtime Integration

When integrating Markdown with JSX in a React ecosystem, developers often encounter two distinct packages: @mdx-js/mdx and @mdx-js/react. While they share the "MDX" name and work together seamlessly, they solve completely different problems in the software lifecycle. One operates at build time to translate syntax, while the other operates at runtime to render components. Understanding this separation is critical for setting up robust content systems, custom frameworks, or advanced documentation sites.

🛠️ Core Responsibility: Compiler vs. Renderer

The fundamental difference lies in their job description. @mdx-js/mdx is a compiler. It takes raw text (Markdown + JSX) and outputs JavaScript code. It does not know about React specifically; it just generates standard ES modules that export a function. @mdx-js/react is a runtime library. It provides the specific React logic needed to take that generated JavaScript function and turn it into visible UI elements in the browser.

@mdx-js/mdx runs during your build process (Node.js environment). It parses the file, applies plugins, and emits code.

// @mdx-js/mdx usage (typically in a build script or loader)
import { compile } from '@mdx-js/mdx';

const mdxContent = '# Hello\n\n<Counter />';

// Compiles raw string into JavaScript code string
const result = await compile(mdxContent, {
  outputFormat: 'function-body',
  development: false
});

console.log(result.value); 
// Output: "function _createMdxContent(props) { ... }"

@mdx-js/react runs in the browser (or server-side rendering context). It supplies the components that the compiled code calls.

// @mdx-js/react usage (in your React App)
import { MDXProvider } from '@mdx-js/react';
import { CompiledMdxComponent } from './generated-file'; // Output from compiler

const components = {
  h1: (props) => <h1 style={{ color: 'tomato' }} {...props} />
};

export default function App() {
  return (
    <MDXProvider components={components}>
      <CompiledMdxComponent />
    </MDXProvider>
  );
}

⚙️ Configuration and Plugin Ecosystem

Configuring how content is processed happens entirely in @mdx-js/mdx. This is where you attach remark plugins (for Markdown analysis) and rehype plugins (for HTML manipulation). If you need to automatically add anchors to headings, transform images, or validate syntax, you do it here. @mdx-js/react has no knowledge of these plugins; it simply receives the final result.

@mdx-js/mdx accepts a rich configuration object to define transformations.

// @mdx-js/mdx: Configuring plugins for build-time transformation
import { compile } from '@mdx-js/mdx';
import remarkGfm from 'remark-gfm';
import rehypeSlug from 'rehype-slug';

await compile(fileContent, {
  remarkPlugins: [remarkGfm], // Enables tables, strikethrough, etc.
  rehypePlugins: [rehypeSlug], // Adds ID attributes to headings
  providerImportSource: '@mdx-js/react' // Tells compiler where to import runtime helpers
});

@mdx-js/react does not accept plugin configurations. Its "configuration" is purely the React Context provided via MDXProvider, which dictates how the final components behave visually.

// @mdx-js/react: No plugin config, only component mapping
import { MDXProvider } from '@mdx-js/react';

// You configure behavior by swapping components, not by passing plugins
const CustomWrapper = ({ children }) => <div className="prose">{children}</div>;

export function Layout({ children }) {
  return (
    <MDXProvider components={{ wrapper: CustomWrapper }}>
      {children}
    </MDXProvider>
  );
}

🔄 Data Flow: From String to Screen

To visualize the data flow, imagine a pipeline. The raw .mdx file enters @mdx-js/mdx. The package outputs a .js file. This .js file is then bundled by your tool (Vite, Webpack, etc.) and imported into your application. Once imported, the code executes and relies on @mdx-js/react to resolve the JSX tags.

If you try to use @mdx-js/mdx in the browser to compile content on the fly, you will face significant performance penalties and large bundle sizes because you are shipping a parser to the client. Conversely, if you try to render compiled MDX without @mdx-js/react, you will get errors about missing components like MDXProvider or useMDXComponents.

@mdx-js/mdx generates code that explicitly imports helpers.

// Output generated by @mdx-js/mdx
import { jsx as _jsx } from 'react/jsx-runtime';
import { useMDXComponents as _provideComponents } from '@mdx-js/react'; // Runtime dependency

export function Content(props) {
  const _components = _provideComponents();
  return _jsx(_components.h1, { children: "Hello World" });
}

@mdx-js/react exports the hooks and providers that satisfy those imports.

// Internal logic simplified from @mdx-js/react
import { useContext, createContext } from 'react';

const MDXContext = createContext({});

export function useMDXComponents(components) {
  // Logic to merge user components with defaults
  return { ...useContext(MDXContext), ...components };
}

export function MDXProvider({ components, children }) {
  return <MDXContext.Provider value={components}>{children}</MDXContext.Provider>;
}

🌐 Deployment and Environment Constraints

Your choice of environment dictates which package is active. @mdx-js/mdx is strictly a Node.js tool. It relies on file system access and heavy parsing libraries that are unsuitable for client-side execution in production. @mdx-js/react is designed for the frontend (React DOM, React Native, or Server Components) and must be included in your final bundle.

@mdx-js/mdx should never be imported in a client-side component unless you are building a specific "live editor" tool and accept the performance cost.

// ❌ Bad Practice: Importing compiler in a client component
import { compile } from '@mdx-js/mdx'; 
// This bloats your bundle with parser logic unnecessary for rendering

// ✅ Good Practice: Using the compiler in a build script (build.mjs)
import { compile } from '@mdx-js/mdx';
// Runs once during deployment to generate static JS files

@mdx-js/react is safe and required for client-side rendering.

// ✅ Correct: Importing runtime in components
import { MDXProvider } from '@mdx-js/react';

export default function BlogPost({ content: Content }) {
  return (
    <article>
      <MDXProvider>
        <Content />
      </MDXProvider>
    </article>
  );
}

🤝 Similarities: Shared Goals

Despite their different roles, both packages are maintained by the same core team and follow strict semantic versioning together. They both aim to decouple content authoring from presentation logic.

1. 🔗 Tight Version Coupling

• Both packages must be on compatible major versions (e.g., v2 with v2, v3 with v3).
• Mismatched versions often lead to runtime errors regarding missing exports or changed function signatures.

// package.json
{
  "dependencies": {
    "@mdx-js/mdx": "^3.0.0",
    "@mdx-js/react": "^3.0.0" // Must match major version
  }
}

2. 🧩 Component Customization

• Both facilitate the goal of overriding default HTML elements.
• The compiler allows setting the import source, while the runtime allows providing the actual components.

// Compiler setting the stage
await compile(content, { providerImportSource: '@mdx-js/react' });

// Runtime delivering the actors
<MDXProvider components={{ p: ParagraphComponent }} />

3. 📝 Standard Compliance

• Both adhere to the CommonMark specification for Markdown and standard JSX syntax.
• They support modern ECMAScript features and tree-shaking to ensure efficient bundles.

// Both support modern import/export syntax
import { compile } from '@mdx-js/mdx'; // ESM
import { MDXProvider } from '@mdx-js/react'; // ESM

📊 Summary: Key Differences

💡 The Big Picture

Think of @mdx-js/mdx as the translator. It takes the author's mixed language of Markdown and JSX and translates it into pure JavaScript that the computer can execute. You interact with it when you set up your build pipeline, configure Vite/Webpack loaders, or write scripts to generate pages.

Think of @mdx-js/react as the actor. It takes the script produced by the translator and performs it on the stage (the DOM). You interact with it in your React components to ensure the content looks right, applies your theme, and handles interactive elements.

Final Thought: In 95% of projects using frameworks like Next.js or Gatsby, you won't import @mdx-js/mdx directly because the framework handles the compilation step for you. However, you will almost always need @mdx-js/react in your package.json and your code to render the content. If you are building a custom engine or a live playground, you will need to orchestrate both: using the compiler to generate code on the server and the runtime to display it on the client.