Authorization-aware Convex component for direct and group messaging with membership enforcement, ordered sends, unread counts, presence, and attachment descript
npm install convex-chatconvex-chat provides a Convex component that manages conversation membership, message ordering, and unread state for direct and group conversations. You install convex-chat@next, register it in convex/convex.config.ts with app.use(chat), then expose host mutations that authenticate the caller and pass their scopeId and subjectId to the component API. Conversation creation stays in host-controlled functions so your application enforces its own relationship and policy rules before the component enforces chat invariants.
convex-chat composes @convex-dev/presence internally to provide online status and typing indicators scoped to conversations. Membership is verified before any presence operation, so clients can only observe and update presence for conversations they belong to. Applications can omit the presence host wrappers entirely if presence is not required by product policy.
convex-chat stores attachment descriptors in its data model but never stores binary data or provider credentials. The host application is responsible for authorizing uploads, resolving download URLs, and deleting objects. The repository includes a working Cloudflare R2 integration via @convex-dev/r2 as a reference for wiring upload grants and conversation authorization in host functions.
convex-chat tracks exact per-conversation unread counts and exposes realtime conversation summaries through its actor-scoped API. Counts update as messages are delivered and marked read, with no polling required because the component builds on Convex's reactive query model.
No. convex-chat never decides whether two users are allowed to start a chat. The host application authenticates callers, enforces relationship and policy rules, and creates the conversation. convex-chat then enforces membership and chat invariants for every subsequent operation. Host table IDs cross the component boundary as opaque strings, so the component has no knowledge of your user model.
Install convex-chat@next from npm. The latest tag currently points to a 0.0.1 name-reservation placeholder and does not include the implemented component. The project is in early alpha and its API and data model may change before the first stable release.
Import the component config and register it in your convex/convex.config.ts file using app.use(chat), where chat is the default export from convex-chat/convex.config.js. Then expose host mutations and queries that authenticate the caller, derive their scopeId and subjectId, and delegate to the generated component API or the exposeChatApi wrappers.
Yes. convex-chat supports replies with deletion-safe quote snapshots, meaning the quoted content is captured at reply time and survives deletion of the original message. It also supports revision-safe edits and delete-for-everyone tombstones, so clients always receive a consistent view of message state.
The repository includes a runnable Next.js example application under apps/example that demonstrates direct messaging, presence, reactions, and Cloudflare R2 attachments. The example uses a deliberately insecure identity switcher for demo purposes and documents how to deploy to Vercel using a monorepo build configuration with a Convex deploy key.