Skip to main content
Streamdown is a drop-in replacement for react-markdown. The props API is 100% compatible — children, components, remarkPlugins, rehypePlugins, remarkRehypeOptions, allowElement, allowedElements, disallowedElements, skipHtml, unwrapDisallowed, and urlTransform all work without changes. Beyond compatibility, switching to Streamdown removes a significant amount of boilerplate: built-in GFM, syntax highlighting, math, mermaid diagrams, prestyled typography, and internal memoization are all included.

​
What changes

​
Package name and import

import ReactMarkdown from "react-markdown";
Streamdown exports the same utility types as react-markdown: 
import type { Options, Components, ExtraProps } from "react-markdown";
If you need a type for the full Streamdown props object: 
import type { StreamdownProps } from "streamdown";

​
Tailwind CSS source path

Streamdown requires Tailwind to scan its built output. Add a @source directive to your globals.css:
globals.css
@source "../node_modules/streamdown/dist/*.js";
For Tailwind v3, add to your content array in tailwind.config.js:
tailwind.config.js
module.exports = {
  content: [
    // ... existing paths
    "./node_modules/streamdown/dist/*.js",
  ],
};
See Getting started for monorepo path adjustments.

​
What you can remove

Streamdown bundles several plugins and components that were previously installed separately.

​
Built-in plugins

The following packages are built into Streamdown. You can uninstall them:
  • rehype-harden
  • rehype-katex
  • rehype-raw
  • remark-cjk-friendly
  • remark-cjk-friendly-gfm-strikethrough
  • remark-gfm
  • remark-math
Check that these packages are not imported or used elsewhere in your project before removing them.

​
Custom code block and mermaid components

Streamdown renders syntax-highlighted code blocks and Mermaid diagrams natively. Any custom code or mermaid component overrides in your ReactMarkdown usage can be deleted. This may also let you uninstall shiki or react-syntax-highlighter from package.json.

​
Custom element overrides for basic elements

Streamdown prestyles all standard HTML elements (p, li, h1–h6, blockquote, table, etc.). If your existing ReactMarkdown usage passes components only to style these basic elements, you can remove those overrides entirely. Similarly, if the wrapper component uses Tailwind’s prose classes for typography, those can be removed.

​
Memoization wrappers

Streamdown handles memoization internally using React.memo and per-block memoization in streaming mode. If your codebase has a MemoizedReactMarkdown wrapper (or equivalent), remove it and use Streamdown directly.

​
What stays the same

All react-markdown props continue to work without modification:
PropTypeDescription
childrenstringThe markdown content to render
componentsComponentsCustom component overrides
remarkPluginsPluggable[]Remark plugins for markdown processing
rehypePluginsPluggable[]Rehype plugins for HTML processing
remarkRehypeOptionsobjectOptions passed to remark-rehype
allowedElementsstring[]Only render these HTML elements
disallowedElementsstring[]Remove these HTML elements
allowElementfunctionCustom filter per element
unwrapDisallowedbooleanKeep children of disallowed elements
skipHtmlbooleanIgnore raw HTML in markdown
urlTransformfunctionTransform all URLs

​
Step-by-step migration

1

Install Streamdown

npm install streamdown
2

Update imports

Replace all react-markdown imports with streamdown:
import ReactMarkdown from "react-markdown";
// Usage:
<ReactMarkdown>{content}</ReactMarkdown>
3

Remove built-in plugins

Uninstall any of these packages if you installed them only for ReactMarkdown:
npm uninstall rehype-harden rehype-katex rehype-raw remark-cjk-friendly remark-gfm remark-math
Remove the corresponding import statements and remarkPlugins/rehypePlugins arrays from your markdown component.
4

Remove custom code block and mermaid components

Delete any custom components you passed as components.code for syntax highlighting or mermaid rendering. Streamdown handles both natively.If you were using shiki or react-syntax-highlighter only for this purpose, uninstall them:
npm uninstall shiki react-syntax-highlighter
5

Remove custom element overrides for basic elements

If your components prop only overrides basic typographic elements (p, li, h1, etc.) for styling, delete those overrides. Streamdown prestyles them.Remove any prose Tailwind classes from the parent container.
6

Remove memoization wrappers

Delete any MemoizedReactMarkdown component or equivalent React.memo wrapper. Import and use Streamdown directly at the call sites.
7

Configure Tailwind CSS

Add the @source directive so Tailwind picks up Streamdown’s utility classes:
globals.css
@source "../node_modules/streamdown/dist/*.js";
Adjust the relative path based on your project structure. See Getting started for monorepo instructions.
8

Clean up wrapper files

Check if any markdown wrapper file now just re-exports Streamdown with no custom props, logic, or styling. If so, delete it and import Streamdown directly at each call site.

​
AI-assisted migration

You can use the following prompt with an AI coding assistant to automate the migration: Copy the prompt below and paste it into your AI coding assistant: 
Can you update this repo to use Streamdown instead of React Markdown.

Migration instructions:

- Replace `import ReactMarkdown from "react-markdown"` (or equivalent) with `import { Streamdown } from "streamdown"`
- If type `Options` is used from react-markdown, create a new type `type Options = ComponentPropsWithoutRef<typeof Streamdown>`
- If type `Components` is used from react-markdown, create a new type `type Components = ComponentPropsWithoutRef<typeof Streamdown>['components']`
- If any of the following plugins are used, you can remove them as they're built in to Streamdown: rehype-harden, rehype-katex, rehype-raw, remark-cjk-friendly, remark-cjk-friendly-gfm-strikethrough, remark-gfm, remark-math. However, check that they're not being used elsewhere first.
- If code blocks or mermaid components exist, you can remove them too as they're built in to Streamdown. This may involve also uninstalling shiki / react-syntax-highlighter from the package.json.
- If the project is using a tailwind.config file, add the following to the `content` array: `'./node_modules/streamdown/dist/*.js',` (ensuring the node modules path is correct).
- If the project is using Tailwind 4 globals.css, add the following near the top under imports: `@source "../node_modules/streamdown/dist/*.js";` (ensuring the node modules path is correct).
- If the old ReactMarkdown component has custom components e.g. p tags, li tags, etc. you can delete them all. These are prestyled in Streamdown.
- If the old ReactMarkdown component uses `prose` classes, you can remove them too.
- When updating deps, use the local package manager as defined by the `packageManager` field in package.json or the lockfile e.g. pnpm-lock.yaml = pnpm.
- When installing Streamdown, use the latest versions of the packages (`streamdown`, `@streamdown/code`, etc.)
- If the old ReactMarkdown component is memoized / a "MemoizedReactMarkdown" (or equivalent) component exists, remove the memoization. Streamdown does this internally.
- Final step: Check if the markdown wrapper file is now redundant. If it just re-exports Streamdown without any custom props, styling, or logic, delete the wrapper file and import Streamdown directly where needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us