Getting started

Install and configure Streamdown in your React application.

Get up and running with Streamdown in minutes. This guide walks you through installation, Tailwind CSS configuration, and your first implementation.

Requirements

• Node.js >= 18
• React >= 18
• Tailwind CSS

Installation

1. Install the package

   Install Streamdown using your preferred package manager:

   npm

   npm install streamdown
   
2. Configure Tailwind CSS

   Streamdown uses Tailwind CSS utility classes internally. Add a @source directive to your globals.css so Tailwind scans Streamdown’s built output:

   globals.css

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

   The path must be relative from your CSS file to the node_modules folder containing streamdown. In a standard Next.js project where globals.css lives in app/, the path above works as-is.

   If you install optional Streamdown plugins (@streamdown/code, @streamdown/math, etc.), add a matching @source line for each one. See the individual plugin pages for exact paths.

   Tailwind v3: Add the path to your content array in tailwind.config.js instead:

   tailwind.config.js

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

   If you plan to use the built-in animated prop for streaming animations, import the animation stylesheet in your app’s root layout:

   app/layout.tsx

   import "streamdown/styles.css";
   
4. Add CSS custom properties

   Streamdown components are built on the shadcn/ui design system and rely on CSS custom properties for colors, border radius, and spacing.

   If you already use shadcn/ui, these variables are set up automatically. Otherwise, add the following minimal set to your global CSS:

   globals.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;
   }
   

   Use the shadcn/ui theme generator to create a custom color palette and paste the generated variables directly into your project.

   Without these variables, components may render with missing backgrounds, incorrect borders, or broken spacing.

5. Render your first component

   Import Streamdown and pass it a markdown string as children:

   app/page.tsx

   import { Streamdown } from "streamdown";
   
   export default function Page() {
     const markdown = "# Hello World\n\nThis is **streaming** markdown!";
   
     return <Streamdown>{markdown}</Streamdown>;
   }
   

   That’s it. Streamdown renders your markdown with GitHub Flavored Markdown, security hardening, and prestyled typography out of the box.

Monorepo setup

In a monorepo (npm workspaces, Turborepo, pnpm workspaces, etc.), dependencies are typically hoisted to the root node_modules. The @source path must point there instead of a local node_modules.

Given this structure:

monorepo/
├── node_modules/streamdown/   ← hoisted here
├── apps/
│   └── web/
│       └── app/
│           └── globals.css    ← your CSS file

Adjust the path with three ../ segments to reach the root:

globals.css

/* apps/web/app/globals.css — 3 levels up to reach root node_modules */
@source "../../../node_modules/streamdown/dist/*.js";

Count the depth from your CSS file to the root node_modules directory and add the appropriate number of ../ segments. Apply the same adjustment for any plugin @source entries.

For Tailwind v3 in a monorepo, update tailwind.config.js similarly:

tailwind.config.js

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