Markdown that draws while the model is still writing

flowdown renders an AI reply in React as it streams: GitHub Markdown plus steps, tabs, figures, diagrams and math. Its own parser, no dependencies, 33 KB.

npm install @localix-ai/flowdown

React 18 and 19 · MIT · Docs · also outside React and in Rust

Streaming a reply

  1. Install
    One package, no dependencies.
    sh
    npm install @localix-ai/flowdown
    
  2. Render
    Pass streaming while the text is still arriving.
    reply.tsxtsx
    import { Markdown } from '@localix-ai/flowdown'
    import '@localix-ai/flowdown/styles.css'
    
    export function Reply({ text, done }) {
      return <Markdown streaming={!done}>{text}</Markdown>
    }
    
  3. Teach the model
    Add answerFormatPrompt() to the system prompt, and it writes these forms.
  • 0.14 sto stream 100k characters
  • 33 KBgzipped
  • 0dependencies

The same reply, outside React:

ts
import { renderToHtml } from '@localix-ai/flowdown/static'

const html = renderToHtml(reply)

Streaming 100k charactersTime
flowdown0.14 s
markdown-to-jsx2.4 s
Streamdown6.5 s

Read more

1,736 characters

Built for a reply, not a document

Seven things it does

Streaming

Nothing half-written reaches the reader

A reply arrives mid-word. Unfinished **bold, a half-typed link and an open code fence are repaired as they come, so raw syntax never shows and nothing flickers when it closes.

arrivesis drawn asThe **answer isThe answer is  (bold)see [the guisee the gui```ts⏎const a =a code block, still open| a | b |⏎| -a table, its first row$$ \frac{1held until it can be setonly the block being written is parsed again

Dialect

Forms a model can write and a reader can scan

Steps, tabs, headline figures, the case for and against, callouts, folded sections, sources and file trees, on top of GitHub Markdown. Each is a quote line and a list: where it is not rendered, it still reads.

Rolling back a deploy

  1. Find the last good release
    git log --oneline --first-parent main
  2. Deploy it
    bun run deploy --ref v1.4.2
  3. Check the health page
    It turns green within a minute.
  • 40 sto roll back
  • 0requests dropped
deploy
releases
v1.4.2the last good one
v1.5.0the bad one
current -> releases/v1.4.2
Why not revert the commit?

A revert builds and ships a new release, which takes minutes. A rollback points current at a release that is already built.

Simplicity is prerequisite for reliability. — Edsger W. Dijkstra

  • rolled back
  • write the incident note

Read more

902 characters

Speed

A long reply costs what a short one does

A 100k-character reply streams in 0.14 s of main-thread time; the next fastest of six React renderers takes 2.4 s. No update takes more than 5 ms, so a stream never drops a frame.

streaming, mschat 5kcode 50kanswer 100kflowdown1048141markdown-to-jsx15632,393markstream411,0765,714Streamdown515,9266,529marked-react37807,709react-markdown2133,808stopped33 KB gzipped, one package, no dependencies

Targets

The same reply outside React

As HTML text on a server, in a page with no framework, as a <flow-down> element, or as the rows of a terminal: this one is @localix-ai/flowdown/tui, live. One parser draws them all, and none of these entries imports React.

Move the API to Bun
▌ Warning
▌ Back up package-lock.json first.
1 Install
│ Run bun install.
│
2 Swap the scripts
Replace node with bun in package.json.
src/server.ts
import { serve } from 'bun'
serve({ port: 3000, fetch: () => new Response('ok') })
- "start": "node dist/server.js"
+ "start": "bun src/server.ts"
│ Check │ Before │ After │
├────────────┼────────┼───────┤
│ Cold start │ 410 ms │ 95 ms │
│ p95 │ 38 ms │ 21 ms │
✓ lockfile backed up
☐ deploy to staging
Throughput is r = n / t, and over k samples
1 k
r̄ = ─ ∑ rᵢ
k i=1
Further reading
[1] Bun runtime — what differs from Node
https://bun.sh/docs/runtime
765 characters

Diagrams and math

A diagram a reader can open

A mermaid fence is drawn once it is whole, in the page’s colours, and opens in a viewer that zooms and pans: try it. Formulas are set by KaTeX. Both load only for a reply that has one.

Between your message and the reply

The page draws while the model writes:

sequenceDiagram
  participant You
  participant App
  participant Model
  You->>App: Send a message
  App->>Model: The conversation
  loop Every token
    Model-->>App: The text so far
    App-->>You: Draw the last block again
  end
  Model-->>App: Done
Drawing diagram…

Hover the diagram for its toolbar: Enlarge opens a viewer that zooms and pans.

With $n$ characters arriving at $r$ a second, the reply takes

$$ t = \frac{n}{r} $$

and each update costs the last block, not the whole text.

577 characters

Safety

A reply cannot act on the page

A model’s text is untrusted. Raw HTML is parsed and sanitized, scripts and handlers are dropped, and a link keeps only a safe protocol. It needs no setup and no second library.

the reply<img src=x onerror="steal()">[click](javascript:alert(1))<script>fetch('/token')</script>the page<img src="x"/><p><a>click</a></p>(nothing)

Rust

The same dialect in Rust

A crate with no dependency reads a reply into a tree, for a terminal, a server or an agent written in Rust. Both parsers pass the same cases of the dialect and teach a model with the same prompt, and the crate builds its tree faster than pulldown-cmark pulls its events.

reading a replyMB/sallocationsflowdown41489pulldown-cmark349262comrak87217,548one crate in the build, no unsafe, any text a document

Documentation

20 pages →

Releases

Full changelog →
  1. v0.7.0

    It draws every kind Mermaid has that cells can say honestly:

    8 changes

  2. v0.6.2

    9babcc0: A badge, an image in a link ([![build](…)](…)), is drawn as its image while its link is still

    1 change

  3. v0.6.1

    4bcefc5: A table that grows row by row is drawn by its last rows only again

    1 change

  4. v0.6.0

    <Markdown>, the page, the element and the terminal view do this by themselves. A target of your own asks for it: createDocument({ refs: true }), then parse(source, { refs: block.refs }) for each block; without the option a text with definitions is one block, as before. parse takes refs, definitions(markdown) of /engine reads the definitions of a text, and splitBlocks and createBlockSplitter take { refs: true }.

    4 changes

  5. v0.5.2

    The package's repository is localixai/flowdown: the links of its page on npm and of its README

    1 change

Start in three steps

Free · MIT license

  1. Install

    npm install @localix-ai/flowdown. React is its only peer, and only for <Markdown>.

  2. Render

    Import @localix-ai/flowdown/styles.css once, then <Markdown streaming={!done}>{text}</Markdown>.

  3. Teach the model

    Add answerFormatPrompt() from @localix-ai/flowdown/prompt to the system prompt.