@toaq-oss/omni-mdx 0.1.11 → 0.1.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -169
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,221 +1,140 @@
|
|
|
1
1
|
# @toaq-oss/omni-mdx
|
|
2
2
|
|
|
3
|
-
The React
|
|
3
|
+
**The high-performance MDX engine.** A unified React & Next.js rendering layer powered by a dual Rust backend (Native Node.js + WebAssembly).
|
|
4
4
|
|
|
5
5
|
[](https://github.com/toaq-oss)
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
This package consumes the ultra-fast Abstract Syntax Tree (AST) generated by our Rust core in WebAssembly (@toaq-oss/core-parser) and transforms it into interactive, secure, and highly customizable React components.
|
|
6
|
+
[](https://omni-core.org/mdx)
|
|
9
7
|
|
|
10
8
|
---
|
|
11
9
|
|
|
12
|
-
## Why
|
|
13
|
-
|
|
14
|
-
Most MDX pipelines (next-mdx-remote, @next/mdx, contentlayer) run at the JS level and require client-side hydration for math, syntax highlighting, and custom components. This means:
|
|
10
|
+
## ⚡ Why Omni-MDX?
|
|
15
11
|
|
|
16
|
-
-
|
|
17
|
-
- Math rendered on the client (flash of unstyled content)
|
|
18
|
-
- Custom components that can't be pure Server Components
|
|
12
|
+
Traditional MDX pipelines are often slow or require complex client-side hydration. `omni-mdx` solves this by moving the heavy lifting to Rust, providing a seamless bridge between raw content and React components.
|
|
19
13
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
14
|
+
- **Dual-Engine Architecture:** Uses native `.node` binaries on the server for maximum speed and **WASM** in the browser for instant live previews.
|
|
15
|
+
- **Zero-Hydration Math:** LaTeX is pre-parsed by Rust and rendered via KaTeX with zero layout shift.
|
|
16
|
+
- **RSC Optimized:** Built from the ground up for Next.js App Router and Server Components.
|
|
17
|
+
- **Non-Blocking:** Offloads parsing from the Node.js main thread to Rust, keeping your server responsive even under heavy load.
|
|
23
18
|
|
|
24
19
|
---
|
|
25
20
|
|
|
26
|
-
##
|
|
27
|
-
|
|
28
|
-
`@toaq-oss/omni-mdx` is designed for scale. While traditional parsers block the Node.js main thread, our parser offloads the heavy lifting to a native Rust core via WebAssembly or N-API.
|
|
21
|
+
## 📖 Documentation
|
|
29
22
|
|
|
30
|
-
|
|
31
|
-
|
|
23
|
+
For full guides, API references, and advanced configuration, visit:
|
|
24
|
+
👉 **[omni-core.org/mdx](https://omni-core.org/mdx)**
|
|
32
25
|
|
|
33
|
-
|
|
34
|
-
In a strict end-to-end benchmark (parsing raw text to an exploitable JSX AST) over 1,000 iterations of a complex document:
|
|
35
|
-
- `@toaq-oss/omni-mdx` is consistently **~30% faster** than the official `@mdx-js/mdx` compiler.
|
|
36
|
-
|
|
37
|
-
**3. Zero Client JS**
|
|
38
|
-
Because the AST is generated on the server and maps directly to React Server Components, the client receives 0 bytes of parsing logic.
|
|
26
|
+
---
|
|
39
27
|
|
|
40
|
-
## Installation
|
|
28
|
+
## 📦 Installation
|
|
41
29
|
|
|
42
30
|
```bash
|
|
43
31
|
npm install @toaq-oss/omni-mdx
|
|
44
|
-
# KaTeX is
|
|
32
|
+
# KaTeX is required for math rendering
|
|
45
33
|
npm install katex
|
|
46
34
|
```
|
|
47
35
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
```
|
|
51
|
-
import
|
|
36
|
+
## Next.js Configuration
|
|
37
|
+
To enable the WebAssembly engine for client-side rendering, update your `next.config.js`:
|
|
38
|
+
```typescript
|
|
39
|
+
/** @type {import('next').NextConfig} */
|
|
40
|
+
const nextConfig = {
|
|
41
|
+
webpack: (config) => {
|
|
42
|
+
config.experiments = { ...config.experiments, asyncWebAssembly: true };
|
|
43
|
+
config.module.rules.push({
|
|
44
|
+
test: /\.wasm$/,
|
|
45
|
+
type: "asset/resource",
|
|
46
|
+
});
|
|
47
|
+
return config;
|
|
48
|
+
},
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
export default nextConfig;
|
|
52
52
|
```
|
|
53
53
|
|
|
54
54
|
---
|
|
55
55
|
|
|
56
|
-
## Usage
|
|
56
|
+
## 🚀 Usage
|
|
57
|
+
### 1. Server-Side Rendering (RSC)
|
|
58
|
+
Recommended for documentation, blogs, and research papers.
|
|
57
59
|
|
|
58
|
-
|
|
60
|
+
> Full example available here :
|
|
61
|
+
> * Basic setup: [TOAQ-oss/omni-core-sandox](https://github.com/TOAQ-oss/omni-mdx-sandbox/tree/main/next/basic-setup)
|
|
62
|
+
> * Advanced rendering : [TOAQ-oss/omni-core-sandox](https://github.com/TOAQ-oss/omni-mdx-sandbox/tree/main/next/advanced-rendering)
|
|
59
63
|
|
|
60
64
|
```tsx
|
|
61
65
|
import { parseMdx, MDXServerRenderer } from "@toaq-oss/omni-mdx/server";
|
|
62
|
-
import {
|
|
63
|
-
|
|
64
|
-
const COMPONENTS = { Note, Details };
|
|
65
|
-
|
|
66
|
-
export default async function ArticlePage({ params }) {
|
|
67
|
-
const content = await getArticleContent(params.slug);
|
|
68
|
-
const ast = await parseMdx(content);
|
|
69
|
-
|
|
70
|
-
return <MDXServerRenderer ast={ast} components={COMPONENTS} />;
|
|
71
|
-
}
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
That's it. No `getStaticProps`, no serialisation workarounds, no client bundle for the content.
|
|
75
|
-
|
|
76
|
-
### Static generation
|
|
66
|
+
import { MyComponent } from "@/components/mdx";
|
|
77
67
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
export async function generateStaticParams() {
|
|
82
|
-
const slugs = await getAllSlugs();
|
|
83
|
-
return slugs.map(slug => ({ slug }));
|
|
84
|
-
}
|
|
68
|
+
export default async function Page({ content }) {
|
|
69
|
+
// Parsed via Native Rust Addon (.node)
|
|
70
|
+
const ast = await parseMdx(content);
|
|
85
71
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
72
|
+
return (
|
|
73
|
+
<MDXServerRenderer
|
|
74
|
+
ast={ast}
|
|
75
|
+
components={{ MyComponent }}
|
|
76
|
+
/>
|
|
77
|
+
);
|
|
90
78
|
}
|
|
91
79
|
```
|
|
92
80
|
|
|
93
|
-
|
|
81
|
+
### 2. Live Client Editor (WASM)
|
|
82
|
+
Perfect for real-time previews or CMS interfaces.
|
|
94
83
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
For live MDX previews where the content changes in the browser:
|
|
84
|
+
> Full example available here : [TOAQ-oss/omni-core-sandox](https://github.com/TOAQ-oss/omni-mdx-sandbox/tree/main/next/client-rendering)
|
|
98
85
|
|
|
99
86
|
```tsx
|
|
100
87
|
"use client";
|
|
101
|
-
import {
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
88
|
+
import { useState } from "react";
|
|
89
|
+
import { parseMdx, MDXClientRenderer } from "@toaq-oss/omni-mdx/client";
|
|
90
|
+
|
|
91
|
+
export default function Editor() {
|
|
92
|
+
const [ast, setAst] = useState(null);
|
|
93
|
+
|
|
94
|
+
const handleChange = async (text) => {
|
|
95
|
+
// Runs 100% locally in the browser via WebAssembly
|
|
96
|
+
const result = await parseMdx(text);
|
|
97
|
+
setAst(result);
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
return (
|
|
101
|
+
<div>
|
|
102
|
+
<textarea onChange={(e) => handleChange(e.target.value)} />
|
|
103
|
+
<MDXClientRenderer ast={ast} />
|
|
104
|
+
</div>
|
|
105
|
+
);
|
|
105
106
|
}
|
|
106
107
|
```
|
|
107
108
|
|
|
108
|
-
The `ast` prop should be computed server-side and passed down, or computed client-side by calling a Route Handler that runs `parseMdx`.
|
|
109
|
-
|
|
110
|
-
---
|
|
111
|
-
|
|
112
|
-
## Import map
|
|
113
|
-
|
|
114
|
-
|Import path|What you get|Where to use|
|
|
115
|
-
|----|---|----|
|
|
116
|
-
|`@toaq-oss/omni-mdx`|Types + `MDX_COMPONENTS` registry|Anywhere|
|
|
117
|
-
|`@toaq-oss/omni-mdx/server`|`parseMdx`, `MDXServerRenderer`, `MDXParseError` |Server Components only|
|
|
118
|
-
|`@toaq-oss/omni-mdx/client`|`MDXClientRenderer`, `MDXErrorBoundary`|Client Components only|
|
|
119
|
-
|
|
120
109
|
---
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
```tsx
|
|
127
|
-
// MDX source:
|
|
128
|
-
// <Note type="warning" title="Heads up">
|
|
129
|
-
// Be careful with **this**.
|
|
130
|
-
// </Note>
|
|
131
|
-
|
|
132
|
-
import { Note } from "@/components/Note"; // can be a Server Component
|
|
133
|
-
import { Details } from "@/components/Details"; // can be a Server Component
|
|
134
|
-
import { Chart } from "@/components/Chart"; // "use client" inside
|
|
135
|
-
|
|
136
|
-
const COMPONENTS = { Note, Details, Chart };
|
|
137
|
-
|
|
138
|
-
const ast = await parseMdx(content);
|
|
139
|
-
return <MDXServerRenderer ast={ast} components={COMPONENTS} />;
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
Server Components in the registry are rendered on the server with zero client JS. Client Components are hydrated normally.
|
|
110
|
+
|Environment|Backend|Entry Point|
|
|
111
|
+
|:---|:---|:---|
|
|
112
|
+
|**Server** (Node.js)|Native Addon (`.node`)|`@toaq-oss/omni-mdx/server`|
|
|
113
|
+
|**Client** (Browser)|WebAssembly (`.wasm`)|`@toaq-oss/omni-mdx/client`|
|
|
114
|
+
|**Edge** (Vercel)|Native Addon (`.wasm`)|`@toaq-oss/omni-mdx/client`|
|
|
143
115
|
|
|
144
116
|
---
|
|
145
117
|
|
|
146
|
-
##
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
118
|
+
## 🧩 Features
|
|
119
|
+
### 📐 Professional Math
|
|
120
|
+
Math is handled via KaTeX. Simply include the CSS in your `layout.tsx`:
|
|
150
121
|
```tsx
|
|
151
|
-
import
|
|
152
|
-
|
|
153
|
-
try {
|
|
154
|
-
const ast = await parseMdx(content);
|
|
155
|
-
} catch (e) {
|
|
156
|
-
if (e instanceof MDXParseError) {
|
|
157
|
-
console.error("MDX syntax error:", e.message);
|
|
158
|
-
console.error("Source:", e.source);
|
|
159
|
-
}
|
|
160
|
-
}
|
|
122
|
+
import "katex/dist/katex.min.css";
|
|
161
123
|
```
|
|
124
|
+
* **Inline:** $E=mc^2$
|
|
125
|
+
* **Block:** $$\int f(x)dx$$
|
|
162
126
|
|
|
163
|
-
###
|
|
164
|
-
|
|
165
|
-
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.
|
|
166
|
-
|
|
167
|
-
You can also use `MDXErrorBoundary` directly:
|
|
168
|
-
|
|
127
|
+
### 🎨 Custom Components
|
|
128
|
+
Register any React component (Server or Client) to handle custom tags:
|
|
169
129
|
```tsx
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
</MDXErrorBoundary>
|
|
130
|
+
const components = {
|
|
131
|
+
Callout: ({ children }) => <div className="p-4 bg-blue-50">{children}</div>,
|
|
132
|
+
VocalDataset: dynamic(() => import('./VocalDataset'), { ssr: false })
|
|
133
|
+
};
|
|
175
134
|
```
|
|
176
135
|
|
|
177
136
|
---
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
| Syntax | Output |
|
|
184
|
-
|---|---|
|
|
185
|
-
| `$E = mc^2$` | `<span class="math math-inline" data-math="…">` |
|
|
186
|
-
| `$$…$$` | `<div class="math math-display" data-math="…">` |
|
|
187
|
-
|
|
188
|
-
KaTeX hydrates the `data-math` attributes on the client via `MDXClientRenderer`, or you can use any KaTeX auto-render script in your layout.
|
|
189
|
-
|
|
190
|
-
---
|
|
191
|
-
|
|
192
|
-
## Runtime support
|
|
193
|
-
|
|
194
|
-
| Runtime | Native `.node` | WASM fallback |
|
|
195
|
-
|-----------------|:--------------:|:-------------:|
|
|
196
|
-
| Node.js 18+ | ✅ | ✅ |
|
|
197
|
-
| Next.js (RSC) | ✅ | ✅ |
|
|
198
|
-
| Edge runtime | ❌ | ✅ |
|
|
199
|
-
| Browser | ❌ | ✅ |
|
|
200
|
-
|
|
201
|
-
The package auto-detects the environment and loads the appropriate backend. No configuration required.
|
|
202
|
-
|
|
203
|
-
---
|
|
204
|
-
|
|
205
|
-
## Building the native addon
|
|
206
|
-
|
|
207
|
-
The `.node` files are pre-built for common platforms. To build for your platform:
|
|
208
|
-
|
|
209
|
-
```bash
|
|
210
|
-
cd core-parser
|
|
211
|
-
napi build --platform --release --features node --no-js
|
|
212
|
-
cp toaq-parser-core.*.node ../packages/mdx-next/native/
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
To build the WASM fallback:
|
|
216
|
-
|
|
217
|
-
```bash
|
|
218
|
-
cd core-parser
|
|
219
|
-
wasm-pack build --target bundler --features wasm
|
|
220
|
-
mv pkg/* ../packages/mdx-next/wasm/
|
|
221
|
-
```
|
|
137
|
+
## 🤝 Contributing
|
|
138
|
+
This package is part of the TOAQ open-source ecosystem.
|
|
139
|
+
* **Core Parser (Rust):** [TOAQ-oss/omni-mdx-core](https://github.com/TOAQ-oss/omni-mdx-core)
|
|
140
|
+
* **Reporting Issues:** Please use the GitHub issue tracker for bugs or feature requests.
|