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.
2. If CLI insights are available, run npx convex insights --details. Use --prod, --preview-name, or --deployment-name when needed.
   • If the local repo's Convex CLI is too old to support insights, try npx -y convex@latest insights --details before giving up.
3. If the repo already uses convex-doctor, you may treat its findings as hints. Do not require it, and do not treat it as the source of truth.
4. If runtime signals are unavailable, audit from code anyway, but keep the guardrails above in mind. Lack of insights is not proof of health, but it is also not proof that a large refactor is warranted.