Performance#

TanStack Markdown’s performance strategy is architectural: keep parsing synchronous, keep the AST simple, split entry points, and leave expensive optional work outside the core.

Current measurements#

The generated browser bundle report records:

React is externalized, and the highlighter measurement uses only a callback stub. Exact generated bytes live in the size report.

The maintained benchmark records parse, pre-parsed rendering, parse-and-render, and external-highlighter paths against the pinned comparison packages. Timings vary by runtime, CPU, fixture shape, and dependency version, so the generated benchmark report is the only source of current CPU results.

Use the narrow entry point#

import { parseMarkdown } from '@tanstack/markdown/parser'
import { renderHtml } from '@tanstack/markdown/html'

Avoid the React adapter in non-React code. Import individual extensions instead of the docs preset when only one capability is required.

Parse ahead of rendering#

For content that changes less often than it is viewed, parse during ingestion or the build. Cache the serializable AST and render it for each target. The measured AST renderer is several times faster than parsing and rendering together.

Keep highlighting external#

Highlighting often costs more than Markdown parsing and can bring language grammars, themes, or WASM. Run it at build time or on the server when possible. The Markdown package will never import a highlighter from its core paths.

Reproduce the reports#

pnpm run size
pnpm run bench

Bundle budgets are also enforced in the test suite so an accidental dependency or code-size regression fails CI.