mdx.do vs. Local Compilation: A Comparison for Dynamic Scenarios

MDX is a game-changer for content. By letting you seamlessly blend JSX components with Markdown, it transforms static documents into rich, interactive experiences. But as its adoption grows, a critical question emerges for developers: What's the best way to compile it?

Traditionally, MDX compilation happens locally during your site's build process. It's a robust method for static sites. But what if your content isn't static? What if it comes from a database, a user input form, or a headless CMS after your site has been deployed?

This is where the paradigm shifts from local compilation to "Compilation as a Service." In this post, we'll compare the traditional local approach with an on-demand API like mdx.do, focusing on which is right for your dynamic content workflows.

The Standard: Local MDX Compilation at Build-Time

Local compilation is the method most developers encounter first. Using tools like next-mdx-remote or Webpack/Vite loaders, you process your .mdx files when you build your application.

How It Works

1. Create Content: You write your content in .mdx files and store them in your project's repository.
2. Configure Build Tools: You set up your build process (e.g., in next.config.js) to recognize and process these files.
3. Build & Deploy: When you run npm run build, your build tool finds all .mdx files, compiles them into JavaScript/React components, and bundles them with your application code.
4. Serve: The final output is a highly optimized, static application where the content is pre-rendered.

Strengths and Weaknesses

This approach is excellent for:

• Blogs where posts are written in the codebase.
• Documentation sites that are versioned with the code.
• Marketing pages with content that rarely changes outside of a deployment.

However, its static nature is also its biggest limitation. Local compilation breaks down when content needs to be dynamic. If your content is generated by users, served from a CMS, or needs to be updated without a new deployment, the build-time model simply doesn't work.

The On-Demand Solution: mdx.do Compilation as a Service

This is where mdx.do introduces a new workflow. Instead of compiling content at build-time, you compile it on-demand with a simple API call.

Think of it as CONTENT AS CODE, delivered dynamically.

How It Works

1. Get Content: Your application fetches an MDX string from any source—a database, a user submission, or a headless CMS.
2. Call the API: You send this string to the mdx.do API.
3. Receive Component & Metadata: The API instantly returns a ready-to-render React component and any parsed frontmatter metadata.

Here's how simple the implementation is with the official SDK:

import { mdx } from '@do-sdk/mdx';

// Your dynamic MDX string from any source
const dynamicContent = `
--- 
title: Hello Dynamic World!
author: 'CMS'
---

# This content was loaded on the fly!

It can even include interactive components like this <LivePreview />.
Imagine the possibilities for user-generated tutorials or live documentation.
`;

// Compile your MDX string into a renderable component
const { component, frontmatter } = await mdx.compile({
  content: dynamicContent
});

// `component` can now be rendered in your React app,
// and `frontmatter` contains your metadata.
// { title: 'Hello Dynamic World!', author: 'CMS' }

Unlocking Dynamic Workflows

This on-demand approach is tailor-made for modern, dynamic applications:

• User-Generated Content (UGC): Allow users to write and submit their own rich content with interactive elements, like a tutorial platform or a community forum.
• Headless CMS Previews: Build a real-time "live preview" feature in your CMS dashboard. As an editor types, the content is sent to mdx.do and rendered instantly, without needing a complex server setup.
• Decoupled Architectures: Your front-end application doesn't need to bundle heavy compilation libraries. It stays lean, simply fetching and rendering content, which keeps your build process fast and simple.
• Personalization: Dynamically assemble and render MDX content tailored to the specific user viewing your application.

Head-to-Head Comparison

Conclusion: Choose the Right Tool for the Job

The choice between local and on-demand MDX compilation isn't about which is "better"—it's about which is right for your specific use case.

Choose local compilation if you're building a classic static site where content and code are deployed together. The performance is unbeatable, and the ecosystem is mature.

Choose mdx.do if you're building a next-generation application where content is fluid and dynamic. If your content lives in a database, comes from your users, or needs to update in real-time, offloading compilation to a dedicated service simplifies your architecture and unlocks powerful new features.

Ready to move beyond the limitations of the build step? Transform your content workflows with mdx.do and start compiling MDX on demand.

Frequently Asked Questions

Q: What is MDX?
A: MDX is an authorable format that lets you seamlessly write JSX in your Markdown documents. It's a powerful way to embed interactive components directly within your content, transforming static documents into rich applications.

Q: How does mdx.do work?
A: mdx.do provides a simple API endpoint. You send an MDX string to the service, and it returns a compiled, ready-to-render React component, along with any frontmatter metadata. This offloads the compilation process from your application's build environment.

Q: Why use mdx.do instead of a local library?
A: Using mdx.do is ideal for dynamic content scenarios where you can't rely on a static build step. It's perfect for user-generated content, CMS-driven pages, or any situation where you need to compile MDX on-demand without complicating your stack.

Q: What is frontmatter?
A: Frontmatter is metadata (like title, author, or tags) written in languages like YAML at the beginning of a Markdown or MDX file. mdx.do automatically parses this for you and returns it as a structured JSON object alongside your component.