Streamdown

react-markdown 的即插即用替换方案，专为 AI 驱动的流式传输设计。

概述

Markdown 格式化简单，但当进行分词和流式传输时会遇到新挑战。Streamdown 专门针对从 AI 模型流式传输 Markdown 内容的特殊需求构建，即使在不完整或未终止的 Markdown 块情况下也能实现无缝格式化。

Streamdown 为 AI Elements Message 组件提供动力，但也可以作为独立包安装以满足您的流式传输需求。

功能

• 🚀 即插即用替换 react-markdown
• 🔄 流式优化 - 优雅处理不完整的 Markdown
• 🎨 未终止块解析 - 使用 remend 构建以提升流式传输质量
• 📊 GitHub 风格 Markdown - 支持表格、任务列表和删除线
• 🔢 数学渲染 - 通过 KaTeX 渲染 LaTeX 公式
• 📈 Mermaid 图表 - 作为代码块渲染 Mermaid 图表，并提供渲染按钮
• 🎯 代码语法高亮 - 使用 Shiki 实现美观的代码块
• 🛡️ 安全优先 - 使用 rehype-harden 构建安全渲染
• ⚡ 性能优化 - 使用记忆化渲染实现高效更新

安装

npm i streamdown

然后更新您的 Tailwind globals.css 以包含以下内容，使 Tailwind 能够检测 Streamdown 使用的实用类。

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

路径必须从您的 CSS 文件到包含 streamdown 的 node_modules 文件夹相对。在标准 Next.js 项目中，globals.css 位于 app/ 目录下，上述默认路径应正常工作。

如果您安装了可选的 Streamdown 插件，请从相关插件文档（/docs/plugins/code、/docs/plugins/cjk、/docs/plugins/math、/docs/plugins/mermaid）添加对应的 @source 行。仅包含实际安装的插件的 @source 条目。

示例：

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

单体仓库设置

在单体仓库（npm 工作区、Turbo、pnpm 等）中，依赖项通常被提升到根 node_modules。您需要调整相对路径以指向那里：

monorepo/
├── node_modules/streamdown/  ← 提升到这里
├── apps/
│   └── web/
│       └── app/
│           └── globals.css   ← 您的 CSS 文件

/* apps/web/app/globals.css → 3 层到根 node_modules */
@source "../../../node_modules/streamdown/dist/*.js";

根据您的 CSS 文件与根 node_modules 的相对位置调整 ../ 段数。如果安装了 Streamdown 插件，请仅在相应包实际安装时添加对应的 @source 条目。

CSS 自定义属性（设计令牌）

Streamdown 组件基于 shadcn/ui 的设计系统构建，并依赖 CSS 自定义属性用于颜色、圆角和间距。如果没有定义这些变量，组件可能会渲染出缺失的背景、边框或错误的间距。

如果您已经使用 shadcn/ui，这些变量会自动设置。如果未使用，请在全局 CSS 中添加以下最小集：

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --radius: 0.625rem;
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);
  --card-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --border: oklch(0.269 0 0);
  --input: oklch(0.269 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --radius: 0.625rem;
}

您也可以使用 shadcn/ui 主题生成器 创建自定义调色板，并将生成的 CSS 变量直接复制到项目中。

使用方式

以下是您在 React 应用中使用 Streamdown 与 AI SDK 的示例：

import { useChat } from "@ai-sdk/react";
import { Streamdown } from "streamdown";
import { code } from "@streamdown/code";
import { mermaid } from "@streamdown/mermaid";
import { math } from "@streamdown/math";
import { cjk } from "@streamdown/cjk";
import "katex/dist/katex.min.css";
import "streamdown/styles.css";

export default function Chat() {
  const { messages, status } = useChat();

  return (
    <div>
      {messages.map(message => (
        <div key={message.id}>
          {message.role === 'user' ? 'User: ' : 'AI: '}
          {message.parts.map((part, index) =>
            part.type === 'text' ? (
              <Streamdown
                key={index}
                animated
                plugins={{ code, mermaid, math, cjk }}
                isAnimating={status === 'streaming'}
              >
                {part.text}
              </Streamdown>
            ) : null,
          )}
        </div>
      ))}
    </div>
  );
}

更多信息请查看 文档。

Streamdown 快速上手指南

环境准备

• 系统要求：Node.js 14+
• 前置依赖：
  • React（用于渲染）
  • Tailwind CSS（需配置全局样式）
  • shadcn/ui（可选，用于设计系统）

安装步骤

1. 安装核心包：

   npm install streamdown
   

   （可选）使用国内镜像加速：

   npm config set registry https://registry.npmmirror.com
   

2. 配置 Tailwind 全局样式： 在 globals.css 添加：

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

   若使用 monorepo 结构，需调整路径指向根 node_modules（如 ../../../node_modules/streamdown/dist/*.js）。

3. 安装可选插件（如需）：

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

   对应添加插件样式引用（如 @source "../node_modules/@streamdown/code/dist/*.js";）。

基本使用

import { useChat } from "@ai-sdk/react";
import { Streamdown } from "streamdown";
import { code, mermaid, math, cjk } from "@streamdown/...";

export default function Chat() {
  const { messages } = useChat();
  return (
    <div>
      {messages.map(message => (
        <div key={message.id}>
          {message.role === 'user' ? 'User: ' : 'AI: '}
          {message.parts.map((part, index) =>
            part.type === 'text' ? (
              <Streamdown
                key={index}
                animated
                plugins={{ code, mermaid, math, cjk }}
              >
                {part.text}
              </Streamdown>
            ) : null,
          )}
        </div>
      ))}
    </div>
  );
}

注意：需同时引入 KaTeX 和 Streamdown 样式：

import "katex/dist/katex.min.css";
import "streamdown/styles.css";