Technical Deep Dive: Using Rust to achieve zero-bundle-size MDX in React Server Components
Hi everyone,
MDX parsing in Next.js has traditionally been a trade-off between build-time performance and client-side hydration costs. In large-scale projects, the Remark/Rehype pipeline can become a significant bottleneck.
We’ve been experimenting with a different approach for Omni-Core: offloading the entire parsing logic to a native Rust core. Here’s a breakdown of the architecture and how it integrates with RSC.
1. The "Single Core" Architecture
Instead of maintaining separate parsers for different environments, we centralized the logic in Rust. This ensures identical parsing behavior whether you're rendering on the web via WASM or in a Python data pipeline.
2. Achieving Zero-JS for Content
By moving the parsing step into Rust and the rendering step into React Server Components, the heavy lifting happens entirely on the server. The result is that the MDX content reaches the browser as pure static HTML.
- The Rust parser generates a "pristine" AST.
- This AST is JSON-serializable, making it easy to cache or pass between server and client.
- Standard UI components are mapped to JSX tags via a registry, allowing Server Components to handle the rendering without sending the parser to the client.
3. The Unified/Rehype Bridge
One challenge was maintaining compatibility with existing plugins. We implemented a bridge that maps the Rust-generated AST directly to the HAST (HTML AST) format. This allows developers to inject standard rehype plugins (like syntax highlighters) into the native pipeline.
4. Hybrid Runtime Execution
To ensure it works everywhere, the engine auto-detects the environment:
- Native .node: High-speed execution for Node.js 18+ and Next.js RSC.
- WASM Fallback: Ensures compatibility with Edge runtimes (Vercel Edge, Cloudflare Workers) and direct browser previews.
5. Native Math Handling
Instead of relying on external JS plugins for equations, we integrated math lexing directly into the Rust core. It outputs standard HTML data attributes that can be statically styled or hydrated with minimal overhead.
We've open-sourced the implementation under Omni-MDX v1.0.0. If you're interested in cross-platform parsing or RSC optimization, the source and full documentation are available below.
Documentation: https://omni-core.org/mdx