Convex Performance Audit

Convex Performance Audit

Diagnose and fix performance problems in Convex applications, one problem class at a time.

When to Use

• A Convex page or feature feels slow or expensive
• npx convex insights --details reports high bytes read, documents read, or OCC conflicts
• Low-freshness read paths are using reactivity where point-in-time reads would do
• OCC conflict errors or excessive mutation retries
• High subscription count or slow UI updates
• Functions approaching execution or transaction limits
• The same performance pattern needs fixing across sibling functions

When Not to Use

• Initial Convex setup, auth setup, or component extraction
• Pure schema migrations with no performance goal
• One-off micro-optimizations without a user-visible or deployment-visible problem

Guardrails

• Prefer simpler code when scale is small, traffic is modest, or the available signals are weak
• Do not recommend digest tables, document splitting, fetch-strategy changes, or migration-heavy rollouts unless there is a measured signal, a clearly unbounded path, or a known hot read/write path
• In Convex, a simple scan on a small table is often acceptable. Do not invent structural work just because a pattern is not ideal at large scale

First Step: Gather Signals

Start with the strongest signal available:

1. If deployment Health insights are already available from the user or the current context, treat them as a first-class source of performance signals.