BoosAPI/desktop/libs/markstream-vue/docs/guide/react-markdown-migration-cookbook.md

react-markdown Migration Cookbook

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

::: tip 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

// before
import Markdown from 'react-markdown'

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

// 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:

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:

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:

<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:

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:

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:

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.

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:

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

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:

<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:

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.

Related docs

• Migrate from react-markdown
• React Installation
• React Components & API
• Parser API