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:
- If deployment Health insights are already available from the user or the
current context, treat them as a first-class source of performance signals.
- 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.
- 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.
- 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.
Signal Routing
After gathering signals, identify the problem class and read the matching
reference file.
| Signal |
Reference |
| High bytes or documents read, JS filtering, unnecessary joins |
references/hot-path-rules.md |
| OCC conflict errors, write contention, mutation retries |
references/occ-conflicts.md |
| High subscription count, slow UI updates, excessive re-renders |
references/subscription-cost.md |
| Function timeouts, transaction size errors, large payloads |
references/function-budget.md |
| General "it's slow" with no specific signal |
Start with references/hot-path-rules.md |
Multiple problem classes can overlap. Read the most relevant reference first,
then check the others if symptoms remain.
Escalate Larger Fixes
If the likely fix is invasive, cross-cutting, or migration-heavy, stop and
present options before editing.
Examples:
- introducing digest or summary tables across multiple flows
- splitting documents to isolate frequently-updated fields
- reworking pagination or fetch strategy across several screens
- switching to a new index or denormalized field that needs migration-safe
rollout
When correctness depends on handling old and new states during a rollout,
consult skills/convex-migration-helper/SKILL.md for the migration workflow.
Workflow
1. Scope the problem
Pick one concrete user flow from the actual project. Look at the codebase,
client pages, and API surface to find the flow that matches the symptom.
Write down:
- entrypoint functions
- client callsites using
useQuery, usePaginatedQuery, or useMutation
- tables read
- tables written
- whether the path is high-read, high-write, or both
2. Trace the full read and write set
For each function in the path:
- Trace every
ctx.db.get() and ctx.db.query()
- Trace every
ctx.db.patch(), ctx.db.replace(), and ctx.db.insert()
- Note foreign-key lookups, JS-side filtering, and full-document reads
- Identify all sibling functions touching the same tables
- Identify reactive stats, aggregates, or widgets rendered on the same page
In Convex, every extra read increases transaction work, and every write can
invalidate reactive subscribers. Treat read amplification and invalidation
amplification as first-class problems.
3. Apply fixes from the relevant reference
Read the reference file matching your problem class. Each reference includes
specific patterns, code examples, and a recommended fix order.
Do not stop at the single function named by an insight. Trace sibling readers
and writers touching the same tables.
4. Fix sibling functions together
When one function touching a table has a performance bug, audit sibling
functions for the same pattern.
After finding one problem, inspect both sibling readers and sibling writers for
the same table family, including companion digest or summary tables.
Examples:
- If one list query switches from full docs to a digest table, inspect the other
list queries for that table
- If one mutation needs no-op write protection, inspect the other writers to the
same table
- If one read path needs a migration-safe rollout for an unbackfilled field,
inspect sibling reads for the same rollout risk
Do not leave one path fixed and another path on the old pattern unless there is
a clear product reason.
5. Verify before finishing
Confirm all of these:
- Results are the same as before, no dropped records
- Eliminated reads or writes are no longer in the path where expected
- Fallback behavior works when denormalized or indexed fields are missing
- New writes avoid unnecessary invalidation when data is unchanged
- Every relevant sibling reader and writer was inspected, not just the original
function
Reference Files
references/hot-path-rules.md - Read amplification, invalidation,
denormalization, indexes, digest tables
references/occ-conflicts.md - Write contention, OCC resolution, hot document
splitting
references/subscription-cost.md - Reactive query cost, subscription
granularity, point-in-time reads
references/function-budget.md - Execution limits, transaction size, large
documents, payload size
Also check the official
Convex Best Practices
page for additional patterns covering argument validation, access control, and
code organization that may surface during the audit.
Checklist
1---2name: convex-performance-audit3description:4 Audits and optimizes Convex application performance across hot-path reads,5 write contention, subscription cost, and function limits. Use this skill when6 a Convex feature is slow or expensive, npx convex insights shows high bytes or7 documents read, OCC conflict errors or mutation retries appear, subscriptions8 or UI updates are costly, functions hit execution or transaction limits, or9 the user mentions performance, latency, read amplification, or invalidation10 problems in a Convex app.11metadata:12 source: https://skillmd.com/skills/get-convex/convex-performance-audit13---1415# Convex Performance Audit1617Diagnose and fix performance problems in Convex applications, one problem class18at a time.1920## When to Use2122- A Convex page or feature feels slow or expensive23- `npx convex insights --details` reports high bytes read, documents read, or24 OCC conflicts25- Low-freshness read paths are using reactivity where point-in-time reads would26 do27- OCC conflict errors or excessive mutation retries28- High subscription count or slow UI updates29- Functions approaching execution or transaction limits30- The same performance pattern needs fixing across sibling functions3132## When Not to Use3334- Initial Convex setup, auth setup, or component extraction35- Pure schema migrations with no performance goal36- One-off micro-optimizations without a user-visible or deployment-visible37 problem3839## Guardrails4041- Prefer simpler code when scale is small, traffic is modest, or the available42 signals are weak43- Do not recommend digest tables, document splitting, fetch-strategy changes, or44 migration-heavy rollouts unless there is a measured signal, a clearly45 unbounded path, or a known hot read/write path46- In Convex, a simple scan on a small table is often acceptable. Do not invent47 structural work just because a pattern is not ideal at large scale4849## First Step: Gather Signals5051Start with the strongest signal available:52531. If deployment Health insights are already available from the user or the54 current context, treat them as a first-class source of performance signals.552. If CLI insights are available, run `npx convex insights --details`. Use56 `--prod`, `--preview-name`, or `--deployment-name` when needed.57 - If the local repo's Convex CLI is too old to support `insights`, try58 `npx -y convex@latest insights --details` before giving up.593. If the repo already uses `convex-doctor`, you may treat its findings as60 hints. Do not require it, and do not treat it as the source of truth.614. If runtime signals are unavailable, audit from code anyway, but keep the62 guardrails above in mind. Lack of insights is not proof of health, but it is63 also not proof that a large refactor is warranted.6465## Signal Routing6667After gathering signals, identify the problem class and read the matching68reference file.6970| Signal | Reference |71| -------------------------------------------------------------- | ----------------------------------------- |72| High bytes or documents read, JS filtering, unnecessary joins | `references/hot-path-rules.md` |73| OCC conflict errors, write contention, mutation retries | `references/occ-conflicts.md` |74| High subscription count, slow UI updates, excessive re-renders | `references/subscription-cost.md` |75| Function timeouts, transaction size errors, large payloads | `references/function-budget.md` |76| General "it's slow" with no specific signal | Start with `references/hot-path-rules.md` |7778Multiple problem classes can overlap. Read the most relevant reference first,79then check the others if symptoms remain.8081## Escalate Larger Fixes8283If the likely fix is invasive, cross-cutting, or migration-heavy, stop and84present options before editing.8586Examples:8788- introducing digest or summary tables across multiple flows89- splitting documents to isolate frequently-updated fields90- reworking pagination or fetch strategy across several screens91- switching to a new index or denormalized field that needs migration-safe92 rollout9394When correctness depends on handling old and new states during a rollout,95consult `skills/convex-migration-helper/SKILL.md` for the migration workflow.9697## Workflow9899### 1. Scope the problem100101Pick one concrete user flow from the actual project. Look at the codebase,102client pages, and API surface to find the flow that matches the symptom.103104Write down:105106- entrypoint functions107- client callsites using `useQuery`, `usePaginatedQuery`, or `useMutation`108- tables read109- tables written110- whether the path is high-read, high-write, or both111112### 2. Trace the full read and write set113114For each function in the path:1151161. Trace every `ctx.db.get()` and `ctx.db.query()`1172. Trace every `ctx.db.patch()`, `ctx.db.replace()`, and `ctx.db.insert()`1183. Note foreign-key lookups, JS-side filtering, and full-document reads1194. Identify all sibling functions touching the same tables1205. Identify reactive stats, aggregates, or widgets rendered on the same page121122In Convex, every extra read increases transaction work, and every write can123invalidate reactive subscribers. Treat read amplification and invalidation124amplification as first-class problems.125126### 3. Apply fixes from the relevant reference127128Read the reference file matching your problem class. Each reference includes129specific patterns, code examples, and a recommended fix order.130131Do not stop at the single function named by an insight. Trace sibling readers132and writers touching the same tables.133134### 4. Fix sibling functions together135136When one function touching a table has a performance bug, audit sibling137functions for the same pattern.138139After finding one problem, inspect both sibling readers and sibling writers for140the same table family, including companion digest or summary tables.141142Examples:143144- If one list query switches from full docs to a digest table, inspect the other145 list queries for that table146- If one mutation needs no-op write protection, inspect the other writers to the147 same table148- If one read path needs a migration-safe rollout for an unbackfilled field,149 inspect sibling reads for the same rollout risk150151Do not leave one path fixed and another path on the old pattern unless there is152a clear product reason.153154### 5. Verify before finishing155156Confirm all of these:1571581. Results are the same as before, no dropped records1592. Eliminated reads or writes are no longer in the path where expected1603. Fallback behavior works when denormalized or indexed fields are missing1614. New writes avoid unnecessary invalidation when data is unchanged1625. Every relevant sibling reader and writer was inspected, not just the original163 function164165## Reference Files166167- `references/hot-path-rules.md` - Read amplification, invalidation,168 denormalization, indexes, digest tables169- `references/occ-conflicts.md` - Write contention, OCC resolution, hot document170 splitting171- `references/subscription-cost.md` - Reactive query cost, subscription172 granularity, point-in-time reads173- `references/function-budget.md` - Execution limits, transaction size, large174 documents, payload size175176Also check the official177[Convex Best Practices](https://docs.convex.dev/understanding/best-practices/)178page for additional patterns covering argument validation, access control, and179code organization that may surface during the audit.180181## Checklist182183- [ ] Gathered signals from insights, dashboard, or code audit184- [ ] Identified the problem class and read the matching reference185- [ ] Scoped one concrete user flow or function path186- [ ] Traced every read and write in that path187- [ ] Identified sibling functions touching the same tables188- [ ] Applied fixes from the reference, following the recommended fix order189- [ ] Fixed sibling functions consistently190- [ ] Verified behavior and confirmed no regressions