This article is auto-synced from its in-app version in Tai.

@nezasa/tai-chat is a reusable, embeddable React chat component backed by TAI's Streaming API. It is one of TAI's Channels — delivering the same chat experience as the Admin Console's TAI Terminal (SSE streaming, session management, thinking / tool-step display, markdown and mermaid / draw.io rendering, file upload, export) to any React application.

If you want to add a TAI-powered chat to an internal tool, a customer-facing app, or an embedded assistant widget, this SDK is the fastest path.

Related documents:

Status: stable release line. Per-commit dev snapshots ship on every push to main; consumers can install @nezasa/tai-chat@latest (stable) or @nezasa/tai-chat@dev (bleeding edge) — see Release channels below. The API surface is stable within a major version and follows semver.

The SDK is published to GitHub Packages under the @nezasa scope. Make sure your .npmrc authenticates to npm.pkg.github.com:

First-time setup requires more than the snippet above — see Consumer setup — GitHub PAT + SSO authorization for the full walkthrough.

React Query is a peer dependency on purpose: most host apps already use it, and sharing a single QueryClient avoids duplicate caches (see TaiChatProvider props).

Axios, marked, DOMPurify, highlight.js, mermaid, and Lucide icons are bundled as regular dependencies — you don't install them yourself.

mermaid, highlight.js, and @tanstack/react-table are lazy-loaded on first use — plain-text conversations don't pay for them. Mermaid's per- diagram-type grammars (flowchart, sequence, gantt, …) are additionally split into their own chunks and only fetched when a diagram of that type appears.

CI enforces a 150 KB gzipped budget on the main entry (make sdk-bundle-check) and grep-asserts the three heavy deps are not reachable from the main bundle, so widget-mode consumers won't silently regress into a multi-megabyte first load.

Before npm install @nezasa/tai-chat will succeed, two things must be in place: the .npmrc above, pointing the @nezasa scope at GitHub Packages, and a GitHub Personal Access Token that is (a) scoped to read packages and (b) SSO-authorized for the nezasa org. The token alone works on personal projects but 401s on org-scoped packages until it's SSO-authorized.

If you haven't already, drop this into your project's .npmrc (or ~/.npmrc) so the registry and auth reference are in one place:

Then follow the four steps below to create and authorize the NPM_TOKEN.

GitHub Packages for @nezasa requires a classic PAT. The newer fine-grained tokens don't support the GitHub Packages API yet.

The token is now created but unusable against @nezasa packages. You need to authorize it for the org's SAML SSO:

Without this step, npm install fails with a 401 Unauthorized that looks like the package doesn't exist — the error message doesn't mention SSO. See GitHub's SAML SSO docs for the org-admin perspective.

Recommended: export NPM_TOKEN=ghp_… in your shell profile (~/.zshrc, ~/.bashrc). The repo-level .npmrc references ${NPM_TOKEN}, so the raw token never touches a committed file. This is what every Nezasa repo's .npmrc already assumes.

Alternatives if you prefer: a machine keychain (security add-generic-password on macOS, pass on Linux) that exports NPM_TOKEN at shell start, or a user-level ~/.npmrc outside any repo.

Don't paste the raw ghp_… value into a committed .npmrc, CI logs, Slack, or PR descriptions; don't share a PAT between engineers (each one creates their own); don't reuse your local PAT for CI — runners use a separate service-account PAT, or secrets.GITHUB_TOKEN inside nezasa/* repos, which GitHub provides automatically.

Before kicking off a full npm install, sanity-check the auth with a one-liner:

A successful run prints the latest published version (e.g. 0.1.1). 401 Unauthorized means the token is missing, expired, lacks read:packages, or isn't SSO-authorized — see step 2.

The SDK is published to GitHub Packages on three dist-tags:

Browse all published versions, dist-tag pointers, and download counts on the package's GitHub Packages page (requires GitHub access to the nezasa org).

Use latest for production code and any deployment you don't want to re-pin every day. Pin to a caret range ("^1.0.0") and React updates safely.

Use dev for cross-repo integration work where you need bleeding-edge SDK changes before they're tagged — e.g. a tripcache-be PR that depends on a new SDK prop you just merged. Snapshot versions are immutable, so reinstalling @dev later picks up the next snapshot. Pin to a specific snapshot (e.g. @0.1.1-dev-20260415120000-abc1234) when you want a deterministic build.

Use pr-<NUMBER> to verify a PR's exact build in a downstream repo before the PR merges. The workflow's job summary (Actions → "SDK Publish" → "Publish snapshot" → bottom of the run page) shows the exact version and the install commands. The dist-tag floats — every push to that PR republishes to the same tag — so re-running npm install @pkg@pr-NNN picks up the latest. When you want a deterministic build, pin to the exact version (e.g. @0.1.2-pr.214-20260509101501-9b4082a). Snapshots are scoped to the PR's lifetime: nothing prunes the immutable versions, but the dist-tag becomes meaningless after merge — you'd install @dev (post-merge) or @latest (post-release) instead.

Note for npm v7+ hosts: snapshot versions are SemVer prereleases (X.Y.Z-pr.NNN-...), so they don't satisfy plain caret ranges like ^X.Y.Z. Install by exact version or dist-tag, and don't commit the resulting package.json / lockfile change to your downstream repo unless you intend to ship that snapshot.

Every snapshot — dev and pr-* — runs through the same build/verify pipeline (bundle-size budget, API-surface snapshot, full test suite, pre-publish smoke test that packs the SDK, installs it into a fresh React project, and mounts each embedding mode in jsdom) before publish. A regression is caught in the PR — not after it's been published.

The bump levels for any change to the SDK are documented in the repo's .changeset/README.md:

Internal contributors: every PR touching sdk-packages/** must include a changeset. CI's Changeset Gate job enforces this.

The minimum setup is a provider + the chat component:

That's it — agent selection, session sidebar, and chat rendering are all handled by the SDK.

The SDK is stateless about auth and routing. Your app is responsible for:

Portal modes keep the chat inside the same React tree as your app, so context, theme, and the React Query cache work transparently — no iframe, no separate runtime.

Live showroom: see Inline, Drawer, and Widget rendered side-by-side at Docs → SDKs → TAI Chat SDK — Showroom. The page includes a prop-toggle panel for the Inline mode and copy-ready snippets for each mode.

<TaiChat> stretches to fill its parent's height. Give it an ancestor with an explicit height (h-screen, h-[600px], a flex parent with flex-1, etc.).

The provider supplies config, theme, and an internal React Query client. It must wrap every <TaiChat* /> in your tree.

The agent prop has three modes:

Extends all <TaiChat> props, adds:

<TaiChatDrawer> defaults sessionsLayout to "accordion" — a sticky "Recent sessions" bar sits between the agent strip and the chat body and expands in place (cap: 320px tall, internal scroll). Pass sessionsLayout="sidebar" for a wide drawer where the full-page panel fits, or sessionsLayout="hidden" to drop sessions UI entirely. Legacy callers using showSessions={true} keep the same intent as before (forces "sidebar"); showSessions={false} forces "hidden".

Extends all <TaiChat> props, adds:

<TaiChatWidget> defaults sessionsLayout to "hidden" — the popup is narrow and meant to feel lightweight. Wider widgets can opt in with sessionsLayout="sidebar" (full-height panel) or sessionsLayout="accordion" (collapsible bar). Legacy showSessions={true} still maps to "sidebar" for back-compat.

Three layouts trade real-estate for discoverability:

The SDK's CSS is scoped under the [data-tai-chat] attribute that the root component writes on its own container. This prevents style leakage in either direction: host styles don't bleed into the chat, chat styles don't touch the host.

Important: color values must be space-separated HSL triplets ("221 83% 53%"), not hex ("#2563EB") or rgb(). The SDK composes colors with opacity via hsl(var(--primary) / 0.4), which requires the raw triplet form. Hex and named colors will silently produce broken theming.

If you'd rather not use the prop, target the variables directly on the [data-tai-chat] container the SDK writes:

Picked up automatically via prefers-color-scheme: dark. To force a mode (e.g. when your app has its own theme toggle), pass theme={{ colorScheme: "dark" }} — the provider writes data-tai-chat-theme="dark" on the root, which overrides the OS preference. This matters for Mermaid diagrams, whose palette is baked into the rendered SVG rather than picked up from CSS.

If you need to render custom UI alongside chat (a dashboard tile, a "recent conversations" list, etc.), the SDK exports its React Query hooks:

Exported hooks:

All hooks use the provider's QueryClient. If you passed your own via TaiChatProvider.queryClient, the SDK's cache lives alongside yours.

The SDK ships with English by default plus 6 starter packs (de, fr, it, nl, pt, es). Pass any pack — or your own partial override — to TaiChatProvider via the strings prop. Missing keys always fall back to English, so a partial override is a safe drop-in.

Non-English packs are best-effort starter translations — useful out of the box, but expect to override individual keys to match your tone or region (see "Partial override" below). When the canonical English pack gains a key, the same key in non-English packs would temporarily fall back to English until a translator passes through; the locales.test.ts guard rejects merges that introduce that fallback for new static-string keys, so each new key must ship with a translation in every pack.

strings accepts Partial<TaiChatStrings>. Override only the keys you want; everything else falls back to English (or to the base pack you spread first).

Hoist the override to a module constant. The provider memoises its context value on the strings reference; an inline literal (one that's re-allocated on every parent render) busts the memo and rebuilds the context — and therefore re-renders every consumer of useTaiChatStrings — on every keystroke:

If the override depends on host state, wrap it in useMemo keyed on that state — same effect, kept in scope:

If your language isn't shipped, type your pack against the TaiChatStrings interface — TypeScript guarantees you cover every key:

Or, if you'd rather not enumerate ~80 keys, type the pack as Partial<TaiChatStrings> and let the runtime fall back to English for the keys you skip — handy when bootstrapping a new locale incrementally.

Most multilingual hosts already track the user's language somewhere (URL locale, profile setting, i18next, react-intl, …). Mirror that into the strings prop and the chat re-renders in the new language with no remount or session loss. Three things to know:

Already wired into a host i18n library? Drive the lookup off whatever it exposes — i18next.language, useIntl().locale, next-intl's useLocale(), etc. — and pass PACKS[hostLocale] (with an en fallback for codes you don't ship):

Keys with interpolated values (counts, dates, dynamic text) are functions so consumers control plural rules and word order without a runtime template parser:

See the TaiChatStrings interface in source for the full list (~80 keys, grouped by UI area).

Per-agent content — the welcome_message and init_suggestions defined on each agent — is not part of TaiChatStrings. It's localized server-side: the backend reads the request's Accept-Language header (forwarded automatically by browsers), picks the best matching locale from the agent's per-locale map (welcome_message_locales, init_suggestions_locales), and serves the flat welcome_message / init_suggestions fields the SDK already consumes. No SDK prop change is required.

Hosts that need to force a specific locale (e.g. for integration tests, or when the host runs in a non-browser environment that does not send Accept-Language) can append ?locale=de to agent API calls; the backend falls back to en for unsupported codes. The supported locale set mirrors the SDK locale packs above (en, de, es, fr, it, nl, pt).

See docs/agents.md for the full schema and locale-resolution priority.

The SDK follows semantic versioning. Breaking changes (prop removal/rename, type changes, exported-component rename, CSS custom property removal) always mean a major version bump.

npm install fails with 401 Unauthorized. Most common cause: the PAT isn't SSO-authorized for the nezasa org. The token alone lets you install from personal repos but 401s on org-scoped packages. Open the token at https://github.com/settings/tokens, click Configure SSO → Authorize next to nezasa, and re-run. See Consumer setup — GitHub PAT + SSO authorization for the full walkthrough. Other causes: PAT missing read:packages scope, PAT expired, $NPM_TOKEN not set in the shell running npm install.

The chat renders but is blank / unstyled. You likely forgot to import the stylesheet. Either add import "@nezasa/tai-chat/style.css" once in your app, or confirm your bundler honors the "sideEffects" entry in the SDK's package.json (default Vite and webpack setups do).

Classes like max-w-3xl do nothing. If your app uses Tailwind 4, its auto-content detector does not scan node_modules by default. Add an @source directive to your Tailwind entry pointing at the SDK:

401 loops. onAuthError is expected to refresh the token and let the SDK retry on the next user action — don't re-render the provider in a way that remounts <TaiChat> on every error.

Session doesn't persist across reloads. Sessions are server-side objects; the SDK picks the most recent one on mount. If you want a specific session re-opened, pass the session ID down via your own state and read the useChatSessions hook.