markstream-react

Markstream React

Use this skill when the host app is React or Next and the task is to wire Markstream safely.

Workflow

1. Confirm the repo is React 18+ or a compatible Next host and accepts a beta renderer API.
2. Install markstream-react plus only the requested optional peers.
3. Import markstream-react/index.css from the app shell or client entry.
4. Choose the entrypoint that matches the rendering boundary.
   • Use markstream-react for the normal client renderer.
   • Use markstream-react/next for the Next-specific component surface.
   • Use markstream-react/server for server rendering without client hooks.
5. Start with content.
   • For streaming or high-frequency AI output, keep content and use built-in smooth streaming first.
     • smoothStreaming="auto" is the default and activates when typewriter={true} or maxLiveNodes <= 0.
     • typewriter only controls the blinking cursor and defaults to false.
     • fade controls node enter and streamed-text fade animations and defaults to true.
   • Streaming vs recovering history: in chat UIs the same renderer starts streaming and later switches to history when final={true}.
     • Streaming: smoothStreaming="auto", fade={false}, typewriter={true}. Smooth pacing handles gradual appearance; fade would flicker.
     • Recovering history: smoothStreaming={false}, fade={true}, typewriter={false}. Content is already complete — pacing would slow it down, but fade gives a polished entry animation.
     • Dynamic switch: smoothStreaming={isStreaming ? 'auto' : false}, fade={!isStreaming}.
   • Move to nodes + final only for worker-preparsed content, shared AST stores, or custom AST control.
   • Remember that htmlPolicy now defaults to safe, and Mermaid strict mode is on by default through mermaidProps.
6. Respect SSR boundaries in Next.
   • Prefer use client, dynamic imports with ssr: false, or other client-only boundaries when browser-only peers are involved.
7. Use renderer-local components before custom parser work.
   • streamingComponents receives parser-backed NodeComponentProps, supports incomplete custom tags, and automatically contributes its keys to the effective customHtmlTags list.
   • htmlComponents receives sanitized HTML attributes plus children; it does not receive the parser node/loading contract.
   • Prefer defineStreamingComponents(...) and defineHtmlComponents(...) for typed maps.
   • Keep scoped setCustomComponents for built-in node overrides or shared compatibility registration.
   • Use parseOptions transforms only when migration requires token or AST changes.
8. Validate with the smallest useful dev, build, or typecheck command.