convex-realtime

Name: convex-realtime - Agent Skill
Rating: 3.4 (190 reviews)
Author: waynesutton

190

Patterns for building reactive apps including subscription management, optimistic updates, cache behavior, and paginated queries with cursor-based loading

Download Folder View on GitHub

CLI Install

Recommended

Use the skills CLI to install this skill with one command. Auto-detects all installed AI assistants.

Method 1 - skills CLI

npx skills i waynesutton/convexskills/skills/convex-realtime

Method 2 - openskills (supports sync & update)

npx openskills install waynesutton/convexskills

Auto-detects Claude Code, Cursor, Codex CLI, Gemini CLI, and more. One install, works everywhere.

Installation Path

Download and extract to one of the following locations:

~/.claude/skills/convex-realtime/

SKILL.md

agents

assets

Skill Instructions

Back

Run with Cloud Agent

No setup needed. Let our cloud agents run this skill for you.

Select Provider

Select Model

Claude Sonnet 4.5

$0.20/task

Best for coding tasks

Environment setup included

Convex Realtime

Build reactive applications with Convex's real-time subscriptions, optimistic updates, intelligent caching, and cursor-based pagination.

Documentation Sources

Before implementing, do not assume; fetch the latest documentation:

Primary: https://docs.convex.dev/client/react
Optimistic Updates: https://docs.convex.dev/client/react/optimistic-updates
Pagination: https://docs.convex.dev/database/pagination
For broader context: https://docs.convex.dev/llms.txt

Instructions

How Convex Realtime Works

Automatic Subscriptions - useQuery creates a subscription that updates automatically
Smart Caching - Query results are cached and shared across components
Consistency - All subscriptions see a consistent view of the database
Efficient Updates - Only re-renders when relevant data changes

Basic Subscriptions

// React component with real-time data
import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
 
function TaskList({ userId }: { userId: Id<"users"> }) {
  // Automatically subscribes and updates in real-time
  const tasks = useQuery(api.tasks.list, { userId });

Conditional Queries

import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
 
function UserProfile({ userId }: { userId: Id<"users"> | null }) {
  // Skip query when userId is null
  const user = useQuery(

Mutations with Real-time Updates

import { useMutation, useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
 
function TaskManager({ userId }: { userId: Id<"users"> }) {
  const tasks =

Optimistic Updates

Show changes immediately before server confirmation:

import { useMutation, useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
import { Id } from "../convex/_generated/dataModel";
 
function TaskItem({ task }: { task: Task }) {
  const

Optimistic Updates for Lists

import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";
 
function useCreateTask(userId: Id<"users">) {
  return useMutation(api.tasks.create).withOptimisticUpdate(
    (localStore,

Cursor-Based Pagination

// convex/messages.ts
import { query } from "./_generated/server";
import { v } from "convex/values";
import { paginationOptsValidator } from "convex/server";
 
export const listPaginated = query({
  args: {
    channelId: v.id("channels"),
    paginationOpts: paginationOptsValidator,

// React component with pagination
import { usePaginatedQuery } from "convex/react";
import { api } from "../convex/_generated/api";
 
function MessageList({ channelId }: { channelId: Id<"channels"> }) {
  const { results

Infinite Scroll Pattern

import { usePaginatedQuery } from "convex/react";
import { useEffect, useRef } from "react";
import { api } from "../convex/_generated/api";
 
function InfiniteMessageList({ channelId }:

Multiple Subscriptions

import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
 
function Dashboard({ userId }: { userId: Id<"users"> }) {
  // Multiple subscriptions update independently
  const user =

Examples

Real-time Chat Application

// convex/messages.ts
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
 
export const list = query({
  args: { channelId: v.id("channels"

// ChatRoom.tsx
import { useQuery, useMutation } from "convex/react";
import { api } from "../convex/_generated/api";
import { useState, useRef, useEffect } from "react";
 
function ChatRoom

Best Practices

Never run npx convex deploy unless explicitly instructed
Never run any git commands unless explicitly instructed
Use "skip" for conditional queries instead of conditionally calling hooks
Implement optimistic updates for better perceived performance
Use usePaginatedQuery for large datasets
Handle undefined state (loading) explicitly
Avoid unnecessary re-renders by memoizing derived data

Common Pitfalls

Conditional hook calls - Use "skip" instead of if statements
Not handling loading state - Always check for undefined
Missing optimistic update rollback - Optimistic updates auto-rollback on error
Over-fetching with pagination - Use appropriate page sizes
Ignoring subscription cleanup - React handles this automatically

References

Convex Documentation: https://docs.convex.dev/
Convex LLMs.txt: https://docs.convex.dev/llms.txt
React Client: https://docs.convex.dev/client/react
Optimistic Updates: https://docs.convex.dev/client/react/optimistic-updates
Pagination: https://docs.convex.dev/database/pagination

if (tasks === undefined) {

return <div>Loading...</div>;

{tasks.map((task) => (

<li key={task._id}>{task.title}</li>

userId ? { userId } : "skip"

if (userId === null) {

return <div>Select a user</div>;

if (user === undefined) {

return <div>Loading...</div>;

return <div>{user.name}</div>;

(api.tasks.list, { userId });

const createTask = useMutation(api.tasks.create);

const toggleTask = useMutation(api.tasks.toggle);

const handleCreate = async (title: string) => {

// Mutation triggers automatic re-render when data changes

await createTask({ title, userId });

const handleToggle = async (taskId: Id<"tasks">) => {

await toggleTask({ taskId });

<button onClick={() => handleCreate("New Task")}>Add Task</button>

{tasks?.map((task) => (

<li key={task._id} onClick={() => handleToggle(task._id)}>

{task.completed ? "✓" : "○"} {task.title}

withOptimisticUpdate

(localStore, args) => {

const { taskId } = args;

const currentValue = localStore.getQuery(api.tasks.get, { taskId });

if (currentValue !== undefined) {

localStore.setQuery(api.tasks.get, { taskId }, {

completed: !currentValue.completed,

<div onClick={() => toggleTask({ taskId: task._id })}>

{task.completed ? "✓" : "○"} {task.title}

const { title, userId } = args;

const currentTasks = localStore.getQuery(api.tasks.list, { userId });

if (currentTasks !== undefined) {

// Add optimistic task to the list

const optimisticTask = {

_id: crypto.randomUUID() as Id<"tasks">,

_creationTime: Date.now(),

localStore.setQuery(api.tasks.list, { userId }, [

handler: async (ctx, args) => {

.withIndex("by_channel", (q) => q.eq("channelId", args.channelId))

.paginate(args.paginationOpts);

api.messages.listPaginated,

{ initialNumItems: 20 }

{results.map((message) => (

<div key={message._id}>{message.content}</div>

{status === "CanLoadMore" && (

<button onClick={() => loadMore(20)}>Load More</button>

{status === "LoadingMore" && <div>Loading...</div>}

{status === "Exhausted" && <div>No more messages</div>}

const { results, status, loadMore } = usePaginatedQuery(

api.messages.listPaginated,

{ initialNumItems: 20 }

const observerRef = useRef<IntersectionObserver>();

const loadMoreRef = useRef<HTMLDivElement>(null);

if (observerRef.current) {

observerRef.current.disconnect();

observerRef.current = new IntersectionObserver((entries) => {

if (entries[0].isIntersecting && status === "CanLoadMore") {

if (loadMoreRef.current) {

observerRef.current.observe(loadMoreRef.current);

return () => observerRef.current?.disconnect();

}, [status, loadMore]);

{results.map((message) => (

<div key={message._id}>{message.content}</div>

{status === "LoadingMore" && <div>Loading...</div>}

(api.users.get, { userId });

const tasks = useQuery(api.tasks.list, { userId });

const notifications = useQuery(api.notifications.unread, { userId });

const isLoading = user === undefined ||

tasks === undefined ||

notifications === undefined;

return <div>Loading...</div>;

<h1>Welcome, {user.name}</h1>

<p>You have {tasks.length} tasks</p>

<p>{notifications.length} unread notifications</p>

returns: v.array(v.object({

_id: v.id("messages"),

_creationTime: v.number(),

content: v.string(),

authorId: v.id("users"),

authorName: v.string(),

handler: async (ctx, args) => {

const messages = await ctx.db

.withIndex("by_channel", (q) => q.eq("channelId", args.channelId))

// Enrich with author names

messages.map(async (msg) => {

const author = await ctx.db.get(msg.authorId);

authorName: author?.name ?? "Unknown",

export const send = mutation({

channelId: v.id("channels"),

authorId: v.id("users"),

content: v.string(),

returns: v.id("messages"),

handler: async (ctx, args) => {

return await ctx.db.insert("messages", {

channelId: args.channelId,

authorId: args.authorId,

content: args.content,

const messages = useQuery(api.messages.list, { channelId });

const sendMessage = useMutation(api.messages.send);

const [input, setInput] = useState("");

const messagesEndRef = useRef<HTMLDivElement>(null);

// Auto-scroll to bottom on new messages

messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });

const handleSend = async (e: React.FormEvent) => {

if (!input.trim()) return;

content: input.trim(),

{messages?.map((msg) => (

<strong>{msg.authorName}:</strong> {msg.content}

onChange={(e) => setInput(e.target.value)}

placeholder="Type a message..."