@dudousxd/nestjs-agent-react

pnpm add @dudousxd/nestjs-agent-react ai @ai-sdk/react

@dudousxd/nestjs-agent-react connects a React app to the /agent endpoints. <AgentProvider> holds the connection once; useAgentChat wraps the Vercel AI SDK v7 useChat with a transport that speaks the backend's SSE protocol, loads a thread's history, re-attaches a streaming turn, gates on quota, and returns a bound transcript, composer and model picker. useChatTranscript turns the streamed messages into a renderable model, and the components are one rendering of it — they ship unstyled, every class yours via classNames.

import { useAgentChat, ChatInput, MessageList } from '@dudousxd/nestjs-agent-react';

function Assistant() {
  const chat = useAgentChat(); // same origin, `/agent`; <AgentProvider> for anything else

  return (
    <div>
      <MessageList messages={chat.messages} status={chat.status} queue={chat.queue} />
      <ChatInput onSubmit={(text) => chat.sendMessage({ text })} />
    </div>
  );
}

ExportsCopy Anchor Link

Subpath @dudousxd/nestjs-agent-react/markdown exports AgentMarkdown — a streaming-aware GFM + KaTeX + Mermaid renderer for renderText, behind its own peers so a plain-text app never pulls them in.

Subpath @dudousxd/nestjs-agent-react/genui exports GenuiProvider, GenerativeUI, useGenerativeUI, GenerativeUIScope and GenuiTree — the headless renderer for server-pushed components (registry, optional catalog validation, versioned resolveComponent, per-item error boundaries, genui:tree frames). Put <GenuiProvider> at the root and MessageItem draws pushed components with no renderUi. It also exports createReactComponentRegistry, one registry for the browser and server rendering. /genui/json-render exports the same provider with a jsonRender option; /genui/server (createReactServerRenderer) and /genui/server/playwright (createPlaywrightCaptureAdapter) render components outside the browser. See the Generative UI guide and Component rendering.

Subpath @dudousxd/nestjs-agent-react/media exports mediaAttachments(), createMediaUpload and MediaUploadError — resumable uploads through nestjs-media (File uploads).

Headless, in the TanStack senseCopy Anchor Link

The components are style-agnostic, but style-agnostic is not headless: a classNames map lets you restyle the markup this package chose, not replace it. useChatTranscript is the model under that markup — grouped part runs, per-message derived values, actions as state machines, windowing, stick-to-bottom — with nothing drawn and no class named:

const transcript = useChatTranscript({
  messages: chat.messages,
  status: chat.status,
  onStop: () => chat.cancel(),
});

transcript.items[0].blocks;        // [{ kind: 'text' | 'reasoning' | 'tools' | 'files' | 'ui' | 'elicitation' | 'sources', … }]
transcript.items[0].copy;          // { available, copied, copy() }
transcript.items[0].edit;          // { isEditing, draft, canSave, save(), getTextareaProps() }
transcript.window;                 // { hiddenCount, canLoadEarlier, loadEarlier() }
transcript.scroll;                 // { isAtBottom, showJumpToLatest, getContainerProps() }
transcript.stop;                   // { available, isStopping, stop() }

MessageList and MessageItem are one rendering of exactly this and keep their existing props, so adopting the model is additive: a host can move to it screen by screen. The full walkthrough — blocks, reasoning, stopping a turn, stick-to-bottom — is in Bring your own UI.

Hydrating from historyCopy Anchor Link

storedMessageToUiMessage maps one persisted StoredMessage row to one UIMessage, but the loop persists one row per model iteration — a turn with tool calls is 2-3 rows (a "checking that..." row, tool-call rows, a final-answer row). Loading a thread with that adapter renders 2-3 separate assistant bubbles, each with its own cost/tokens footer, for what the live stream rendered as one continuous response.

storedThreadToUiMessages(messages) merges consecutive assistant rows (no user message between them) into a single UIMessage per turn, concatenating parts in step order — a reloaded thread matches the live stream bubble-for-bubble. The merged message carries metadata.usage with summed tokens and cost (costUsd is null only when every merged row's cost is unknown — unknown is never coerced to 0). useAgentChat({ threadId }) does this for you; use it yourself to seed initialMessages from history you already have (SSR, a cache):

const thread = await backend.getThread(threadId);
const chat = useAgentChat({ threadId, initialMessages: storedThreadToUiMessages(thread.messages) });

Reconciling after a run settlesCopy Anchor Link

useAgentChat({ onRunSettled }) fires exactly once per run — { runId, status: 'completed' | 'failed' } — when its stream settles, on both the send and the resume paths. By the time it fires the server has already persisted the thread's title and the run's terminal state, which is the signal onFinish doesn't give you: onFinish only means "a turn rendered here," not "the server is done writing." Use it to refetch thread/list queries so a header or sidebar showing "Untitled" picks up the derived title:

const chat = useAgentChat({
  threadId,
  onRunSettled: ({ status }) => {
    if (status === 'completed') queryClient.invalidateQueries({ queryKey: threadListQueryKey });
  },
});

This matters more than it used to: under a durable backend, AgentModule.forRoot({ durable: true }) dispatches a turn's model call and tool executions as routed durable steps — the actual LLM/tool work can run on a different worker than the pod holding this SSE connection, and results flow back through a cross-process token sink (e.g. Redis) instead of an in-process buffer. The /agent/chat SSE contract this package speaks doesn't change, but a run can keep progressing, or finish, on infrastructure this tab has no direct line to — onRunSettled (and resume, for reattaching to a run still in flight on mount) are the client-side hooks that make that invisible.

Peer dependenciesCopy Anchor Link

When to use itCopy Anchor Link

Reach for -react when the frontend is React and you want the streaming + HITL + thread machinery handled for you. Apps on another framework, or wanting full control over the wire protocol, can build directly against AgentClient or the raw /agent/* REST + SSE surface described in Endpoints.

See Frontend for the full hook option table, wiring headers to identity, rendering approve/reject, and reopening an existing thread.