convex-unread-tracking

Real-time unread message counter and read receipt tracker for Convex.

Tracks read positions per user per channel, supports bulk subscriptions via groups, and provides accurate unread counts. Built as a Convex Component.

Features

• Read position tracking — watermark-based with explicit unread/read range overrides
• Message accounting — register/unregister messages for accurate unread counts
• Unread counts — single channel, total across subscriptions, or batch fetch
• Subscription management — subscribe/unsubscribe/mute senders/archive channels
• Group operations — bulk subscribe/unsubscribe entire teams
• React hooks — optimistic mark-as-read with localStorage offline support
• Cleanup utility — cron-friendly mutation for garbage collection

Installation

npm install convex-unread-tracking

Setup

1. Register the component

// convex/convex.config.ts
import { defineApp } from "convex/server";
import unreadTracking from "convex-unread-tracking/convex.config";

const app = defineApp();
app.use(unreadTracking);

export default app;

2. Create your backend functions

// convex/unreads.ts
import { UnreadTracking } from "convex-unread-tracking";
import { components } from "./_generated/api.js";
import { mutation, query } from "./_generated/server.js";
import { v } from "convex/values";

const unreads = new UnreadTracking(components.unreadTracking);

export const sendMessage = mutation({
  args: { channelId: v.string(), userId: v.string(), text: v.string() },
  handler: async (ctx, args) => {
    const now = Date.now();
    const msgId = await ctx.db.insert("messages", { ...args, timestamp: now });

    // Register with unread tracking (same transaction)
    await unreads.insertMessage(ctx, {
      channelId: args.channelId,
      timestamp: now,
      authorId: args.userId,
    });

    return msgId;
  },
});

export const markRead = mutation({
  args: { userId: v.string(), channelId: v.string(), timestamp: v.number() },
  handler: async (ctx, args) => {
    await unreads.markReadUpTo(ctx, args);
  },
});

export const getUnreadCount = query({
  args: { userId: v.string(), channelId: v.string() },
  handler: async (ctx, args) => {
    return await unreads.getUnreadCount(ctx, args);
  },
});

3. Subscribe users to channels

export const subscribe = mutation({
  args: { userId: v.string(), channelId: v.string() },
  handler: async (ctx, args) => {
    await unreads.subscribe(ctx, args);
  },
});

API Reference

Read Position Tracking

Method	Description
markReadUpTo(ctx, { userId, channelId, timestamp })	Mark everything up to timestamp as read
markReadRange(ctx, { userId, channelId, start, end })	Mark a specific range as read
markOneUnread(ctx, { userId, channelId, timestamp })	Mark a single item as unread
getLastRead(ctx, { userId, channelId })	Get read position for scroll anchor
getLastReads(ctx, { userId, channelIds })	Batch fetch read positions

Message Accounting

Method	Description
insertMessage(ctx, { channelId, timestamp?, authorId? })	Register a message for unread counting
deleteMessage(ctx, { channelId, timestamp })	Remove a message from tracking

Unread Counts

Method	Description
getUnreadCount(ctx, { userId, channelId })	Count for a single channel
getTotalUnreadCount(ctx, { userId })	Aggregate across all subscriptions
getSingleUnreads(ctx, { userId, channelIds })	Batch fetch per-channel counts

Subscription Management

Method	Description
subscribe(ctx, { userId, channelId })	Start tracking unreads
unsubscribe(ctx, { userId, channelId })	Stop tracking (mute)
muteSender(ctx, { userId, targetUserId })	Filter out a sender
unmuteSender(ctx, { userId, targetUserId })	Remove sender filter
archive(ctx, { channelId })	Stop all tracking for a channel

Group Operations

Method	Description
addToGroup(ctx, { groupId, userId })	Add user to a group
removeFromGroup(ctx, { groupId, userId })	Remove from group
subscribeAll(ctx, { groupId, channelId })	Subscribe entire group
unsubscribeAll(ctx, { groupId, channelId })	Unsubscribe entire group

Cleanup

// convex/crons.ts
import { cronJobs } from "convex/server";
const crons = cronJobs();
crons.daily("cleanup unreads", { hourUTC: 3, minuteUTC: 0 },
  internal.unreads.cleanup);
export default crons;

React Hooks

import { useMarkAsRead, useOptimisticUnreadCount } from "convex-unread-tracking/react";

function Channel({ channelId }) {
  const { markRead, getPendingTimestamp, confirmRead } = useMarkAsRead();

  // Optimistic count — shows 0 immediately after marking read
  const serverCount = useQuery(api.unreads.getUnreadCount, { userId, channelId });
  const count = useOptimisticUnreadCount(serverCount, getPendingTimestamp(channelId) !== null);

  const handleMarkRead = async () => {
    markRead(channelId, Date.now()); // optimistic
    await markReadMutation({ userId, channelId, timestamp: Date.now() });
    confirmRead(channelId); // confirm sync
  };
}

Demo

Live Demo

License

MIT