react-markdown Migration Cookbook

This page complements the main migration guide with focused before/after examples.

Prefer a runnable example?

See the hosted React migration demo for the same before/after shapes rendered inside the React playground.

Use this page when you already know you want to migrate, and need to answer a specific question such as:

How do I replace components.code?
What happens to remark-gfm?
What do I do with rehype-raw?
How do I replace urlTransform?
What about allowedElements?

1. Plain renderer swap

tsx

// before
import Markdown from 'react-markdown'

export function Article({ markdown }: { markdown: string }) {
  return <Markdown>{markdown}</Markdown>
}

tsx

// after
import MarkdownRender from 'markstream-react'
import 'markstream-react/index.css'

export function Article({ markdown }: { markdown: string }) {
  return <MarkdownRender content={markdown} />
}

2. `components.h1` and `components.a`

react-markdown customizes rendered HTML tags:

tsx

import Markdown from 'react-markdown'

<Markdown
  components={{
    h1({ children }) {
      return <h1 className="docs-title">{children}</h1>
    },
    a({ href, children }) {
      return <a href={href} target="_blank" rel="noreferrer">{children}</a>
    },
  }}
>
  {markdown}
</Markdown>

markstream-react customizes node types:

tsx

import type { NodeComponentProps } from 'markstream-react'
import MarkdownRender, { setCustomComponents } from 'markstream-react'

function CustomHeading({ node, ctx, renderNode, indexKey }: NodeComponentProps<any>) {
  const Tag = `h${node.level || 1}` as keyof JSX.IntrinsicElements

  return (
    <Tag className="docs-title">
      {node.children?.map((child: any, i: number) =>
        renderNode && ctx
          ? renderNode(child, `${String(indexKey)}-heading-${i}`, ctx)
          : null,
      )}
    </Tag>
  )
}

function CustomLink({ node, ctx, renderNode, indexKey }: NodeComponentProps<any>) {
  return (
    <a href={node.href} target="_blank" rel="noreferrer">
      {node.children?.map((child: any, i: number) =>
        renderNode && ctx
          ? renderNode(child, `${String(indexKey)}-link-${i}`, ctx)
          : null,
      )}
    </a>
  )
}

setCustomComponents('docs', {
  heading: CustomHeading,
  link: CustomLink,
})

export function Article({ markdown }: { markdown: string }) {
  return <MarkdownRender customId="docs" content={markdown} />
}

3. `components.code`

Many react-markdown apps override code to add syntax highlighting:

tsx

<Markdown
  components={{
    code({ className, children, ...rest }) {
      const isBlock = /language-/.test(className || '')

      if (isBlock) {
        return (
          <pre className="docs-code">
            <code className={className} {...rest}>
              {children}
            </code>
          </pre>
        )
      }

      return <code {...rest}>{children}</code>
    },
  }}
>
  {markdown}
</Markdown>

In markstream-react, choose one of these:

Keep the default CodeBlockNode
Switch code_block to MarkdownCodeBlockNode
Set renderCodeBlocksAsPre

Example with MarkdownCodeBlockNode:

tsx

import MarkdownRender, { MarkdownCodeBlockNode, setCustomComponents } from 'markstream-react'

setCustomComponents('docs', {
  code_block: ({ node, isDark, ctx }: any) => (
    <MarkdownCodeBlockNode
      node={node}
      isDark={isDark}
      stream={ctx?.codeBlockStream}
      {...(ctx?.codeBlockProps || {})}
    />
  ),
})

export function Article({ markdown }: { markdown: string }) {
  return <MarkdownRender customId="docs" content={markdown} />
}

4. `remark-gfm`

Many react-markdown examples add:

tsx

import remarkGfm from 'remark-gfm'

<Markdown remarkPlugins={[remarkGfm]}>{markdown}</Markdown>

With markstream-react, do not re-add a plugin by default.

Start by removing it and verify whether your actual content still renders correctly. Tables, task lists, strikethrough, and code fences are already common use cases for the parser. If your app depended on very specific plugin behavior, review the output before calling the migration complete.

5. `rehype-raw`

Typical react-markdown setup:

tsx

import Markdown from 'react-markdown'
import rehypeRaw from 'rehype-raw'

<Markdown rehypePlugins={[rehypeRaw]}>{markdown}</Markdown>

In markstream-react, there is no public rehype stage.

Recommended migration path:

If you only needed standard HTML rendering, verify the built-in HTML behavior.
If you used trusted custom tags such as <thinking>, move to customHtmlTags.

tsx

import type { NodeComponentProps } from 'markstream-react'
import MarkdownRender, { setCustomComponents } from 'markstream-react'

function ThinkingNode({ node }: NodeComponentProps<any>) {
  return <aside className="thinking-box">{node.content}</aside>
}

setCustomComponents('chat', { thinking: ThinkingNode })

export function Message({ markdown }: { markdown: string }) {
  return (
    <MarkdownRender
      customId="chat"
      content={markdown}
      customHtmlTags={['thinking']}
    />
  )
}

6. `urlTransform`

Typical react-markdown URL rewriting:

tsx

function rewriteDocsUrl(url: string) {
  if (url.startsWith('/docs/'))
    return `https://example.com${url}`
  return url
}

<Markdown urlTransform={rewriteDocsUrl}>{markdown}</Markdown>

In markstream-react, split this into two concerns:

parseOptions.validateLink for allow/deny decisions
custom link or image renderers for rewriting

tsx

import type { NodeComponentProps } from 'markstream-react'
import MarkdownRender, { setCustomComponents } from 'markstream-react'

function rewriteDocsUrl(url: string) {
  if (url.startsWith('/docs/'))
    return `https://example.com${url}`
  return url
}

function CustomLink({ node, ctx, renderNode, indexKey }: NodeComponentProps<any>) {
  const href = rewriteDocsUrl(node.href)

  return (
    <a href={href}>
      {node.children?.map((child: any, i: number) =>
        renderNode && ctx
          ? renderNode(child, `${String(indexKey)}-link-${i}`, ctx)
          : null,
      )}
    </a>
  )
}

setCustomComponents('docs', { link: CustomLink })

export function Article({ markdown }: { markdown: string }) {
  return <MarkdownRender customId="docs" content={markdown} />
}

7. `allowedElements`

Typical react-markdown filtering:

tsx

<Markdown allowedElements={['h1', 'h2', 'p', 'a', 'code', 'pre']}>
  {markdown}
</Markdown>

There is no direct equivalent prop in markstream-react.

Recommended rule:

If the allowlist is light and non-critical, migrate the renderer first and leave a TODO.
If the allowlist is security-sensitive or user-facing, filter the parsed node tree before rendering.

That means this is usually a manual migration item, not an automatic 1:1 replacement.

8. Streaming as a second pass

Once the static migration is stable, you can move to the parser-driven nodes flow for chat/SSE/AI rendering:

tsx

import MarkdownRender from 'markstream-react'
import { getMarkdown, parseMarkdownToStructure } from 'stream-markdown-parser'

const md = getMarkdown('chat')
const nodes = parseMarkdownToStructure(buffer, md, { final: done })

export function Message() {
  return <MarkdownRender nodes={nodes} viewportPriority deferNodesUntilVisible />
}

This step is optional. Do not force it when the repository only needs static markdown rendering.

react-markdown Migration Cookbook ​

1. Plain renderer swap ​

2. components.h1 and components.a ​

3. components.code ​

4. remark-gfm ​

5. rehype-raw ​

6. urlTransform ​

7. allowedElements ​

8. Streaming as a second pass ​

Related docs ​