Next.js & React Integration

Last Updated March 22, 2026

The @toaq-oss/omni-mdx package is the React/Next.js visual rendering engine of the TOAQ-oss MDX ecosystem. It consumes the ultra-fast Abstract Syntax Tree (AST) generated by our Rust core and transforms it into interactive, secure, and highly customizable React components.

Why This Exists

Most MDX pipelines run at the JS level and require client-side hydration for math, syntax highlighting, and custom components. This traditional approach causes several issues:

• A large JS bundle sent to every visitor.
• Math rendered on the client (flash of unstyled content).
• Custom components that can’t be pure Server Components.

@toaq-oss/omni-mdx solves this by moving the parse step into Rust and the render step into React Server Components. The result is zero JS for content — everything is HTML by the time it reaches the browser.

Data Serialization & Caching

The AST generated by parseMdx is a standard JavaScript Object (POJO). This means it is 100% JSON-serializable. You can safely store the AST in Redis, a database, or use Next.js cache() without any performance penalty during retrieval.

Server Components (Recommended)

The most efficient way to use Omni-MDX is within Next.js App Router Server Components.

import { parseMdx, MDXServerRenderer } from "@toaq-oss/omni-mdx/server";
import { Note, Details }               from "@/components/mdx";

const COMPONENTS = { Note, Details };

export default async function ArticlePage({ params }) {
  const content = await getArticleContent(params.slug);
  const ast     = await parseMdx(content);

  return ;
}

Because parseMdx is async and runs on the server, it works naturally with generateStaticParams for Static Site Generation (SSG). At next build, Next.js calls parseMdx once per article and pre-renders everything to static HTML. The Rust parser never runs in the browser.

Live Editor (Client-Side)

For live MDX previews where the content changes directly in the browser, you can use the client renderer:

"use client";
import { MDXClientRenderer } from "@toaq-oss/omni-mdx/client";

export function LivePreview({ ast, components }) {
  return ;
}

The ast prop should be computed server-side and passed down, or computed client-side by calling a Route Handler that runs parseMdx.

Component Registry

You can map JSX tags found in your MDX directly to your own React components. Register components by name — the key matches the JSX tag in the MDX source:

import { Note }    from "@/components/Note";    // can be a Server Component
import { Details } from "@/components/Details"; // can be a Server Component
import { Chart }   from "@/components/Chart";   // "use client" inside

const COMPONENTS = { Note, Details, Chart };

Server Components in the registry are rendered on the server with zero client JS. Client Components are hydrated normally.

Image Optimization

By default, Omni-MDX renders standard <img> tags. To use the Next.js Image component for automatic optimization (WebP, lazy loading), map it in your registry:

import Image from "next/image";

const COMPONENTS = {
  img: (props) => (
    
  ),
};

Error Handling

Parse Errors

When generating the AST on the server, you can catch syntax issues using the custom MDXParseError class:

import { parseMdx, MDXParseError } from "@toaq-oss/omni-mdx/server";

try {
  const ast = await parseMdx(content);
} catch (e) {
  if (e instanceof MDXParseError) {
    console.error("MDX syntax error:", e.message);
    console.error("Source:", e.source);
  }
}

Component Boundaries

In MDXClientRenderer, every custom component is automatically wrapped in MDXErrorBoundary. If a component throws, the error is isolated — the rest of the document continues to render.

Math & KaTeX

Math is parsed natively in Rust. To maintain Zero JS for content, Omni-MDX outputs static HTML attributes (data-math).

• Static Rendering: If you only need the layout, just import the CSS.
• Interactive Hydration: Use MDXClientRenderer if you need complex KaTeX features in the browser.

// Required for any math rendering
import "katex/dist/katex.min.css";

Runtime Detection

The package auto-detects the environment and loads the appropriate backend without any configuration required.

• Native .node execution: Supported on Node.js 18+ and Next.js (RSC).
• WASM Fallback: Available across all environments, including Edge runtimes and the Browser.