react-remark

react-remark exposes a small set of React primitives — the useRemark and useRemarkSync hooks, and a Remark component — that convert Markdown source strings into real React elements. Rather than dangerously injecting raw HTML, it runs Markdown through the same remark → mdast → remark-rehype → hast → rehype-react pipeline used across the broader unified/remark ecosystem, so Markdown is parsed into a syntax tree, transformed, converted to HTML’s tree representation, and finally rendered as React elements.

Because the pipeline is just unified under the hood, consumers can drop in any existing remark or rehype plugin — GFM tables, KaTeX math, raw HTML with sanitization, syntax highlighting, autolinked headings — via the same remarkPlugins/rehypePlugins arrays those plugins already expect. useRemark is async and event-driven (an input’s onChange can push a new source string on every keystroke), while useRemarkSync renders synchronously for server-side rendering scenarios where async plugin resolution isn’t needed.

What You Get

• A useRemark hook returning a [reactContent, setMarkdownSource] tuple for async, event-driven Markdown rendering.
• A useRemarkSync hook for synchronous rendering, suited to server-side rendering where async plugin resolution isn’t available.
• A Remark component that accepts Markdown as children and handles the hook wiring internally, re-rendering when children change.
• Full access to remark and rehype plugin arrays (remarkPlugins, rehypePlugins) plus per-stage options objects (remarkParseOptions, remarkToRehypeOptions, rehypeReactOptions) for every stage of the pipeline.

Common Use Cases

• Rendering live-editable Markdown previews as a user types
• Server-rendering Markdown-based blog or docs pages with useRemarkSync
• Adding GFM tables, math (KaTeX), or autolinked headings via remark/rehype plugins
• Safely rendering user-submitted Markdown by combining rehype-raw and rehype-sanitize

Under The Hood

Architecture The entire library lives in one ~100-line file, src/index.ts, which exports three primitives — useRemarkSync, useRemark, and Remark — all built by composing a unified() processor chain (remarkParse → user remarkPlugins → remarkToRehype → user rehypePlugins → rehypeReact) with createElement/Fragment injected as the React renderer target. useRemark wraps the async unified .process() call in a useCallback-memoized setter alongside useState for the resulting ReactElement, and exposes an onError callback for failure handling; useRemarkSync instead calls the synchronous .processSync() variant directly, with no state involved. The Remark component composes useRemark internally, running the pipeline in a useEffect keyed on children so it re-renders whenever the Markdown source or options change. There’s no internal module boundary beyond this single file — the library is a thin adapter layer over the unified/remark/rehype pipeline, not an independent processing engine, so changes to unified’s plugin composition contract are what would break this component.

Tech Stack A TypeScript library targeting React >=16.8 (peer dependency) and Node >=10, built on the unified/remark/rehype ecosystem: remark-parse ^9 for Markdown-to-mdast parsing, remark-rehype ^8 for mdast-to-hast conversion, rehype-react ^6 for hast-to-React-element conversion, and unified ^9 as the processor/plugin-chain runtime. Build tooling is tsdx, a zero-config TypeScript package bundler wrapping Rollup and Babel, producing CJS (dist/index.js) and ESM (dist/react-remark.esm.js) outputs plus type declarations. The dev/test stack uses @testing-library/react-hooks and react-test-renderer for hook testing, Storybook 6 for interactive usage examples deployed to GitHub Pages, and husky plus pinst to gate npm publish behind git hooks; Renovate is configured for automated dependency updates.

Code Quality Tests live in test/remark-hook.test.ts and test/remark-component.test.tsx, using @testing-library/react-hooks’ renderHook/act together with Jest snapshot testing, covering base rendering, GFM via remark-gfm, raw HTML via rehype-raw/rehype-sanitize, math via remark-math/rehype-katex, and custom element overrides via rehypeReactOptions.components, for both the async and sync hooks. No test explicitly exercises the onError callback’s failure path, though the API surface makes errors visible via callback rather than swallowing them. Types are used throughout the public API (UseRemarkOptions, UseRemarkSyncOptions, RemarkProps) with no any present, and CI runs via a GitHub Actions workflow with a tsdx lint script available, though no standalone eslint config sits at the repo root beyond tsdx’s bundled defaults. Overall: tested across the main plugin-composition scenarios with snapshots, strictly typed, but error-path and edge-case coverage is thin.

API Design The API surface is minimal and idiomatic — two hooks and one component, mirroring React’s own useState-shaped return tuples so consumers familiar with hooks need no new mental model. Every configuration option is optional and mirrors the underlying unified/remark/rehype option names directly (remarkParseOptions, remarkToRehypeOptions, rehypeReactOptions, remarkPlugins, rehypePlugins) rather than inventing a new abstraction, which keeps the learning curve low for anyone who already knows remark/rehype since upstream docs transfer directly. Getting started is a two-line import and call with no boilerplate. The tradeoff is that consumers unfamiliar with the unified plugin ecosystem must learn it to do anything beyond default rendering, and the library exposes the full underlying pipeline via passthrough options rather than a curated subset. It isn’t conceptually novel — a thin, well-considered React adapter over an existing pipeline rather than a new Markdown-rendering approach.