Stream-MDX DevX Catalog

A practical catalog of the StreamMDX feature surface, focused on production workflows.

This page is intentionally scoped for fast reading: one section per capability, one copy-paste example, and one link to the deeper guide.

Quickstart

Install the convenience package:

npm install stream-mdx

Minimal React usage:

"use client";

import { StreamingMarkdown } from "stream-mdx";

export function Demo({ text }: { text: string }) {
  return (
    <StreamingMarkdown
      text={text}
      worker="/workers/markdown-worker.js"
      features={{ html: true, tables: true, math: true, mdx: true }}
    />
  );
}

• API detail: /docs/public-api
• Integration guide: /docs/react-integration

Architecture and Streaming Model

StreamMDX is worker-first:

1. text chunks arrive
2. worker compiles/parses to block updates
3. renderer applies incremental patches

This keeps render throughput stable under frequent updates.

• Deep dive: /docs/guides/architecture-and-internals
• Throughput behavior: /docs/guides/performance-and-backpressure

Feature Toggles and Plugin Surface

Enable only what you need:

<StreamingMarkdown
  text={text}
  worker="/workers/markdown-worker.js"
  features={{
    html: false,
    tables: true,
    math: true,
    mdx: true,
  }}
/>

For advanced behavior, configure document plugins in the worker bootstrap.

• Cookbook: /docs/plugins-cookbook
• Security defaults: /docs/security-model

Rendering and Theming

Map default nodes onto your design system components:

const htmlElements = {
  table: ({ className, ...props }) => (
    <table className={`w-full text-sm ${className ?? ""}`.trim()} {...props} />
  ),
  blockquote: ({ className, ...props }) => (
    <blockquote className={`border-l-2 pl-4 italic ${className ?? ""}`.trim()} {...props} />
  ),
};

<StreamingMarkdown
  text={text}
  htmlElements={htmlElements}
  worker="/workers/markdown-worker.js"
/>

• Styling guide: /docs/guides/rendering-and-styling
• HTML showcase: /showcase/html-overrides

MDX and Component Embeds

Use custom components in streamed markdown safely:

import { StreamingMarkdown } from "stream-mdx";
import { YouTube } from "./YouTube";
import { Preview } from "./Preview";

const mdxComponents = { YouTube, Preview };

<StreamingMarkdown
  text={text}
  worker="/workers/markdown-worker.js"
  mdxComponents={mdxComponents}
  features={{ mdx: true }}
  mdxCompileMode="worker"
/>

• Guide: /docs/guides/mdx-and-html
• Showcase: /showcase/mdx-components

Math and Mermaid (Optional Add-ons)

Math and Mermaid are opt-in to keep the baseline bundle lean.

import { MermaidBlock } from "@stream-mdx/mermaid";

<StreamingMarkdown
  text={text}
  worker="/workers/markdown-worker.js"
  features={{ math: true }}
  components={{ mermaid: MermaidBlock }}
/>

• Mermaid guide: /docs/guides/mermaid-diagrams
• Performance notes: /docs/guides/performance-and-backpressure

Performance, Metrics, and Guardrails

Start with a conservative profile, then measure:

<StreamingMarkdown
  text={text}
  worker="/workers/markdown-worker.js"
  onMetrics={(m) => {
    console.log({ parseMs: m.parseMs, diffMs: m.diffMs, shikiMs: m.shikiMs });
  }}
/>

Use the perf harness to compare profiles and capture deterministic baselines.

• Perf harness: /docs/perf-harness
• Changelog discipline: /docs/perf-quality-changelog
• Testing guide: /docs/guides/testing-and-baselines

Deployment and Security

Recommended production setup:

1. build hosted worker
2. ship it from static assets
3. keep sanitization on for untrusted HTML
4. use CSP that matches your embed surface

npm -w @stream-mdx/worker run build:hosted
cp packages/markdown-v2-worker/dist/hosted/markdown-worker.js apps/docs/public/workers/markdown-worker.js

• Deployment guide: /docs/guides/deployment-and-security
• Security model: /docs/security-model

Next Steps

• For API contracts, start at /docs/public-api.
• For app integration patterns, use /docs/react-integration.
• For route-by-route examples, browse /showcase.