streamdown

Streamdown

專為串流最佳化的 React Markdown 渲染器。可直接無縫替換 react-markdown，內建串流渲染支援、安全性防護與互動控制項。

快速開始

1. 安裝

npm install streamdown

可選外掛套件（依需求安裝即可）：

npm install @streamdown/code @streamdown/mermaid @streamdown/math @streamdown/cjk

2. 設定 Tailwind CSS（必要步驟）

這是最常被遺漏的步驟。 Streamdown 採用 Tailwind 進行樣式設計，必須掃描 dist 產出檔。

Tailwind v4 — 新增至 globals.css：

@source "../node_modules/streamdown/dist/*.js";

僅針對已安裝的套件新增外掛的 @source 設定（忽略未安裝的外掛可避免 Tailwind 發生錯誤）。詳細路徑請參閱各外掛說明頁面：

• Code：@source "../node_modules/@streamdown/code/dist/*.js";
• CJK：@source "../node_modules/@streamdown/cjk/dist/*.js";
• Math：@source "../node_modules/@streamdown/math/dist/*.js";
• Mermaid：@source "../node_modules/@streamdown/mermaid/dist/*.js";

Tailwind v3 — 新增至 tailwind.config.js：

module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/streamdown/dist/*.js",
  ],
};

3. 基本用法

import { Streamdown } from 'streamdown';

<Streamdown>{markdown}</Streamdown>

4. 搭配 AI 串流（Vercel AI SDK）

'use client';
import { useChat } from '@ai-sdk/react';
import { Streamdown } from 'streamdown';
import { code } from '@streamdown/code';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();

  return (
    <>
      {messages.map((msg, i) => (
        <Streamdown
          key={msg.id}
          plugins={{ code }}
          caret="block"
          isAnimating={isLoading && i === messages.length - 1 && msg.role === 'assistant'}
        >
          {msg.content}
        </Streamdown>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} disabled={isLoading} />
      </form>
    </>
  );
}

5. 靜態模式（適用於部落格、文件）

<Streamdown mode="static" plugins={{ code }}>
  {content}
</Streamdown>

核心 Props 說明

Prop	型態	預設值	用途
children	string	—	Markdown 內文內容
mode	"streaming" | "static"	"streaming"	渲染模式
plugins	{ code?, mermaid?, math?, cjk? }	—	功能外掛套件
isAnimating	boolean	false	串流中動畫指示器
caret	"block" | "circle"	—	游標樣式
components	Components	—	自訂 HTML 元素複寫
controls	boolean | object	true	互動按鈕控制項
linkSafety	LinkSafetyConfig	{ enabled: true }	連結確認彈窗防護
shikiTheme	[light, dark]	['github-light', 'github-dark']	程式碼主題
className	string	—	容器 CSS 類別
allowedElements	string[]	全部	允許的標籤名稱
disallowedElements	string[]	[]	不允許的標籤名稱
allowElement	AllowElement	—	自訂元素過濾函式
unwrapDisallowed	boolean	false	保留被禁用元素的子內容
skipHtml	boolean	false	忽略原始 HTML 標籤
urlTransform	UrlTransform	defaultUrlTransform	URL 轉換與清理（Sanitize）

完整 API 參考說明請參閱 references/api.md。

外掛套件快速參考

外掛套件	套件名稱	用途
Code	@streamdown/code	程式碼語法高亮（Shiki，支援 200+ 種語言）
Mermaid	@streamdown/mermaid	圖表繪製（流程圖、時序圖等）
Math	@streamdown/math	經由 KaTeX 渲染 LaTeX（需匯入 CSS）
CJK	@streamdown/cjk	中日韓（CJK）文字斷行與排版支援

Math 外掛必須匯入 CSS：

import 'katex/dist/katex.min.css';

外掛設定細節請參閱 references/plugins.md。

參考文件

深入了解實作細節請參閱以下文件：

• references/api.md — 完整的 Props、型態與介面定義
• references/plugins.md — 外掛套件的安裝、設定與客製化
• references/styling.md — CSS 變數、data 屬性、自訂元件與主題範例
• references/security.md — 安全強化、連結防護、自訂 HTML 標籤與正式環境配置
• references/features.md — 游標、修復機制（remend）、靜態模式、控制項、GFM、記憶化（Memoization）與疑難雜症排查

設定範例

可直接複製並改寫 assets/examples/ 中的範例：

• basic-streaming.tsx — 搭配 Vercel AI SDK 的極簡 AI 聊天室
• with-caret.tsx — 帶有方塊游標（Block caret）的串流渲染
• full-featured.tsx — 包含所有外掛、游標、連結防護與控制項的全功能範例
• static-mode.tsx — 部落格與文件渲染
• custom-security.tsx — 專為 AI 內容設計的嚴格安全性設定

常見陷阱與注意事項（Gotchas）

1. 缺少 Tailwind 樣式 — 記得在設定檔中新增 @source 指示詞或將 node_modules/streamdown/dist/*.js 加入 content 清單
2. 數學公式未正常渲染 — 請確認是否已匯入 katex/dist/katex.min.css
3. 未顯示游標 — 必須同時傳入 caret prop 且將 isAnimating 設定為 true
4. 串流過程中的複製按鈕 — 當 isAnimating={true} 時，複製按鈕會自動停用
5. 跳出連結安全確認彈窗 — 預設為啟用狀態；若要停用請設定 linkSafety={{ enabled: false }}
6. Next.js 出現 Shiki 警告 — 請顯式安裝 shiki 並將其加入 transpilePackages 設定中
7. allowedTags 無法作用 — 此設定僅在使用預設 rehype 外掛時生效
8. 數學公式預設使用 $$ 而非 $ — 為避免與貨幣符號衝突，預設停用單一符號 $