cursor-plugin-convex-rule-use-pagination-for-large-datasets

Use cursor-based pagination for large datasets instead of .collect(). Prevents performance issues and provides smooth infinite scroll.

Jump to install

Repository: KunanonJ/ai-skills-hub
Last source activity: July 10, 2026 at 16:00
Detected SKILL.md language: English
Stars: 4
Forks: 1

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/KunanonJ/ai-skills-hub --skill cursor-plugin-convex-rule-use-pagination-for-large-datasets

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

import { query } from "./_generated/server";
import { paginationOptsValidator } from "convex/server";

export const listTasks = query({
  args: {
    paginationOpts: paginationOptsValidator,
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);

    return await ctx.db
      .query("tasks")
      .withIndex("by_user", q => q.eq("userId", user._id))
      .order("desc")
      .paginate(args.paginationOpts);
  },
});

{
  page: Doc<"tasks">[],        // Current page of results
  continueCursor: string,      // Cursor for next page
  isDone: boolean,             // True if no more pages
}

import { usePaginatedQuery } from "convex/react";
import { api } from "../convex/_generated/api";

function TaskList() {
  const { results, status, loadMore } = usePaginatedQuery(
    api.tasks.listTasks,
    {},
    { initialNumItems: 20 }
  );

  return (
    <div>
      {results?.map(task => (
        <TaskItem key={task._id} task={task} />
      ))}

      {status === "CanLoadMore" && (
        <button onClick={() => loadMore(20)}>Load More</button>
      )}

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

import { useEffect, useRef } from "react";

function InfiniteTaskList() {
  const { results, status, loadMore } = usePaginatedQuery(
    api.tasks.listTasks,
    {},
    { initialNumItems: 20 }
  );

  const observerRef = useRef<IntersectionObserver>();
  const loadMoreRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (observerRef.current) observerRef.current.disconnect();

    observerRef.current = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting && status === "CanLoadMore") {
        loadMore(20);
      }
    });

    if (loadMoreRef.current) {
      observerRef.current.observe(loadMoreRef.current);
    }

    return () => observerRef.current?.disconnect();
  }, [status, loadMore]);

  return (
    <div>
      {results?.map(task => (
        <TaskItem key={task._id} task={task} />
      ))}

      {status === "CanLoadMore" && (
        <div ref={loadMoreRef} className="h-20 flex items-center justify-center">
          Loading more...
        </div>
      )}
    </div>
  );
}

export const listTasks = query({
  args: {
    status: v.optional(v.union(
      v.literal("todo"),
      v.literal("done")
    )),
    paginationOpts: paginationOptsValidator,
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);

    let query = ctx.db
      .query("tasks")
      .withIndex("by_user", q => q.eq("userId", user._id));

    // Filter in TypeScript after query
    const results = await query.order("desc").paginate(args.paginationOpts);

    if (args.status) {
      return {
        ...results,
        page: results.page.filter(task => task.status === args.status),
      };
    }

    return results;
  },
});

// schema.ts
tasks: defineTable({
  userId: v.id("users"),
  status: v.string(),
}).index("by_user_and_status", ["userId", "status"])

// Query with index
export const listTasks = query({
  args: {
    status: v.union(v.literal("todo"), v.literal("done")),
    paginationOpts: paginationOptsValidator,
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);

    return await ctx.db
      .query("tasks")
      .withIndex("by_user_and_status", q =>
        q.eq("userId", user._id).eq("status", args.status)
      )
      .order("desc")
      .paginate(args.paginationOpts);
  },
});

// Items are inserted/deleted while user scrolls
// Convex automatically handles this!

const { results } = usePaginatedQuery(api.tasks.listTasks, {}, { initialNumItems: 20 });

// Results stay consistent even as data changes
// No duplicates, no missing items

import { getPage } from "convex-helpers/server/pagination";

export const customPagination = query({
  args: {
    category: v.string(),
    paginationOpts: paginationOptsValidator,
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);

    // Custom query logic
    const results = await ctx.db
      .query("posts")
      .withIndex("by_user", q => q.eq("userId", user._id))
      .filter(q => q.eq(q.field("category"), args.category))
      .collect();

    // Apply custom pagination
    return getPage(results, args.paginationOpts);
  },
});

export const searchTasks = query({
  args: {
    searchTerm: v.string(),
    paginationOpts: paginationOptsValidator,
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);

    const allTasks = await ctx.db
      .query("tasks")
      .withIndex("by_user", q => q.eq("userId", user._id))
      .collect();

    // Filter by search term
    const filtered = allTasks.filter(task =>
      task.title.toLowerCase().includes(args.searchTerm.toLowerCase())
    );

    // Paginate filtered results
    return getPage(filtered, args.paginationOpts);
  },
});

interface PaginationOptions {
  numItems: number;      // How many items per page
  cursor: string | null; // Cursor from previous page (null for first page)
  id?: string;          // Optional: Specific ID to paginate from
}

// Usage
const page1 = await query.paginate({ numItems: 20, cursor: null });
const page2 = await query.paginate({ numItems: 20, cursor: page1.continueCursor });

const { results, status, loadMore } = usePaginatedQuery(
  api.tasks.list,
  {},
  { initialNumItems: 20 }
);

<button
  onClick={() => loadMore(20)}
  disabled={status !== "CanLoadMore"}
>
  {status === "LoadingMore" ? "Loading..." : "Load More"}
</button>

const [showAll, setShowAll] = useState(false);

const { results } = usePaginatedQuery(
  api.tasks.list,
  {},
  { initialNumItems: showAll ? 100 : 10 }
);

<button onClick={() => setShowAll(!showAll)}>
  {showAll ? "Show Less" : "Show All"}
</button>

const [activeTab, setActiveTab] = useState<"todo" | "done">("todo");

const { results } = usePaginatedQuery(
  api.tasks.listByStatus,
  { status: activeTab },
  { initialNumItems: 20 }
);

// Separate pagination per tab

Use Indexes

// ✅ Fast
.withIndex("by_user", q => q.eq("userId", userId))
.paginate(opts)

// ❌ Slow
.filter(q => q.eq(q.field("userId"), userId))
.paginate(opts)

Reasonable Page Sizes

// ✅ Good: 10-50 items per page
{ initialNumItems: 20 }

// ❌ Too small: Too many requests
{ initialNumItems: 5 }

// ❌ Too large: Slow loading
{ initialNumItems: 500 }

Order Matters

// ✅ Use .order() for consistent pagination
.query("tasks")
.withIndex("by_created")
.order("desc")
.paginate(opts)

export const debugCount = query({
  handler: async (ctx) => {
    const count = (await ctx.db.query("tasks").collect()).length;
    console.log(`Total tasks: ${count}`);
    return count;
  },
});

const { results, status } = usePaginatedQuery(api.tasks.list, {}, { initialNumItems: 20 });

console.log({
  itemsLoaded: results?.length,
  status,
  canLoadMore: status === "CanLoadMore"
});

name	cursor-plugin-convex-rule-use-pagination-for-large-datasets
description	Use cursor-based pagination for large datasets instead of .collect(). Prevents performance issues and provides smooth infinite scroll.
metadata	{"version":"0.1.0"}

name	cursor-plugin-convex-rule-use-pagination-for-large-datasets
description	Use cursor-based pagination for large datasets instead of .collect(). Prevents performance issues and provides smooth infinite scroll.
metadata	{"version":"0.1.0"}

cursor-plugin-convex-rule-use-pagination-for-large-datasets

Install options

Review the source files

Use Pagination for Large Datasets

The Problem with .collect()

❌ Bad: Loading Everything

✅ Good: Pagination

Use Pagination for Large Datasets

The Problem with .collect()

❌ Bad: Loading Everything

✅ Good: Pagination

When to Paginate

✅ Always Paginate:

⚠️ Maybe Don't Paginate:

Basic Pagination

Backend: Query with Pagination

Frontend: usePaginatedQuery

Infinite Scroll Pattern

Pagination with Filters

Reactive Pagination

The Challenge (Other Systems)

Convex Solution

Advanced: Custom Pagination

Search with Pagination

Pagination Options

Common Patterns

Pattern 1: Load More Button

Pattern 2: Show/Hide Older Items

Pattern 3: Paginated Tabs

Performance Tips

Debugging Pagination

Check Total Items (Dev Only)

Log Pagination State

Checklist

Learn More

cursor-plugin-convex-rule-use-pagination-for-large-datasets

Source facts

Install options

Review the source files

More from this repository

More from this repository

Use Pagination for Large Datasets

The Problem with .collect()

❌ Bad: Loading Everything

✅ Good: Pagination

Use Pagination for Large Datasets

The Problem with .collect()

❌ Bad: Loading Everything

✅ Good: Pagination

When to Paginate

✅ Always Paginate:

⚠️ Maybe Don't Paginate:

Basic Pagination

Backend: Query with Pagination

Frontend: usePaginatedQuery

Infinite Scroll Pattern

Pagination with Filters

Reactive Pagination

The Challenge (Other Systems)

Convex Solution

Advanced: Custom Pagination

Search with Pagination

Pagination Options

Common Patterns

Pattern 1: Load More Button

Pattern 2: Show/Hide Older Items

Pattern 3: Paginated Tabs

Performance Tips

Debugging Pagination

Check Total Items (Dev Only)

Log Pagination State

Checklist

Learn More