Introduction

@mordn/chat-widget is a React/Next.js chat surface backed by a single mounted server handler. It provides conversation ownership, idempotent persistence, history, private attachments, and streaming while keeping identity and policy on your server.

Identity is established on your server

The browser never tells the server who it is. Implement getChatUserId(request) from a verified session; the handler must not trust any client-supplied id. The store and storage factories are then bound to that server-derived identity.

Minimum integration decisions

Identity

Resolve the user from a verified server session.

Model

Provide a Vercel AI SDK model in code or through hosted configuration.

Persistence

Provide a Drizzle, hosted, or custom ChatStoreFactory.

Tools and attachment storage are optional. Omitting storage disables uploads.

Request flow

code

Browser ChatWidget
  → createChatHandler
    → getUserId(request)
    → ChatStoreFactory(verifiedUserId)
    → optional StorageAdapterFactory(verifiedUserId)
    → model + optional tools/retrieval/memory

createChatHandler returns GET, POST, DELETE, and OPTIONS. Export OPTIONS when using its cross-origin CORS support.

Start here

Quickstart

Install and mount the shipped contracts.

Security model

Understand the identity boundary.

Choosing a backend

Select persistence and storage.

API reference

Review every server option.