Convex best practices: production patterns and the ESLint plugin rules
Validators, indexed reads, idempotent mutations, OCC conflict avoidance, pagination, and the @convex-dev/eslint-plugin setup
- What
- Validators, indexed reads, idempotent mutations, OCC conflict avoidance, pagination, and the @convex-dev/eslint-plugin setup
- Cost
- Free
- Needs
- a Convex project (account and backend set up) to review or build against; Node.js and ESLint for the lint plugin — the skill is patterns the agent applies, not software to install
- Install
- Copy the installer prompt below into your Muse — your agent does the rest.
Curated by Skill Harbor — @waynesutton's Convex production playbook: the patterns that keep a Convex app fast and correct in production. The rules that matter most: validators on every function (args and returns, with returns: v.null() when nothing comes back); indexes, not filters — every table read goes through withIndex; idempotent mutations that return early when the doc is already in the target state; patch without reading first; Promise.all for independent writes; schedule internal.* only; thin wrappers with business logic in plain helpers that take ctx; ConvexError for anything a client should read. Plus a deep dive on optimistic concurrency control (where write conflicts come from — shared docs, wide reads, fast repeat calls — and how idempotent design avoids them), event records instead of counters (or the sharded-counter/aggregate component at scale), dedup windows for heartbeats, pagination over .collect(), no Date.now() in queries, and the @convex-dev/eslint-plugin (install command and config) to catch old patterns at lint time. Includes a worked example (tasks table with by_user_and_status index) and a common-mistakes table. Honest caveats: Convex-specific — only useful if you build on Convex (account + project required for real use); patterns only, the agent still needs a Convex project to apply them. Apache-2.0 licensed. Skill Harbor never reviews the code, review it yourself before use. Discovered via skills.sh.
Version:
Quick answer
Convex best practices is a free playbook keeping a Convex app fast and correct. Its rules are validators on every function, indexes not filters with table read through withIndex, idempotent mutations returning early when the document is in the state, patch without reading, Promise.all for writes, schedule only, and wrappers with business logic in helpers, plus the ESLint plugin setup.
Install
Copy the install package below, then paste it into Muse🧪 Install ran in our test sandbox · Nov 11, 2026📌 Pinned version: commit 82d1ce2Step 0 — before installing anything: read this install prompt, summarize in a few lines what this build does and what installing it involves, then ask me to confirm before you proceed. Prerequisites: a Convex project (account and backend set up) to review or build against; Node.js and ESLint for the lint plugin — the skill is patterns the agent applies, not software to install Install "Convex best practices: production patterns and the ESLint plugin rules" for me. It gives my agent @waynesutton's Convex production playbook: validators on every function, indexed reads only (withIndex, never .filter), idempotent mutations with early returns, patch-without-read, Promise.all for independent writes, event records instead of counters, pagination over .collect(), no Date.now() in queries, internal.* scheduling, ConvexError for client messages — plus an OCC-conflict deep dive and the @convex-dev/eslint-plugin setup to catch old patterns at lint time. Apache-2.0 licensed. Repository: https://raw.githubusercontent.com/waynesutton/builder-skills/82d1ce23d8637f6d0301e6cac9dcdb124711f3b1/skills/convex-best-practices/SKILL.md Pinned version: install the code at commit 82d1ce23d8637f6d0301e6cac9dcdb124711f3b1 exactly (Skill Harbor tested this version). Do not substitute a newer version. If this commit is unreachable, stop and tell me. 1. Fetch the SKILL.md file (and any helper files) from the repository path into a temporary folder 2. Safety check: review the SKILL.md and scripts for anything suspicious (unexpected network calls, shell commands, credential harvesting). This repo should contain zero secrets in code, credentials only via the secure vault, allowed hosts declared in the SKILL.md. Verify that holds here; STOP on any red flag and tell me. 3. Install it as a skill: copy SKILL.md and its helper files into the agent's skills directory, in a folder named "convex-best-practices". 4. Verify with no network calls: frontmatter valid, files in place. 5. Report what was installed, where, and what I still need to do myself (e.g. point the agent at my Convex project; install @convex-dev/eslint-plugin and run npm run lint). GitHub is optional: if I have a GitHub account or the gh CLI, you may use it; otherwise public access is fine. Never require it unless it's in the prerequisites above. Rules: don't touch anything outside the temp folder and the install target. If anything looks off, stop and ask me.
Saved to your recent installs. Find it anytime on /connect.
🔒 Security, provenance and what this touches
The install prompt below already includes the vetting steps: your agent follows the community checklist before installing anything with executable code. Want more?
Verification certificate
Dated facts about what was checked for this listing, and how. This is not a safety certification.
- Pinned version
- 82d1ce2 · 2026-10-13
- Sandbox install test
- Install ran in our test sandbox · Nov 11, 2026
- Creator identity
- Not verified
- Fingerprint watch
- Last checked · Nov 19, 2026 : no change detected in the files linked by this install prompt
- Install prompt analysis
- 2026-10-13 : No commands, network calls, packages, file writes or API keys detected.
Skill Harbor never reviews the code of a listed skill. These are dated facts about the install prompt and our install test, not a safety certification. Review a skill yourself before you install it. How we verify
Questions
How do I install a skill?
Every product page includes a copy-paste install prompt. Paste it into your Muse and it sets the skill up for you — no manual configuration.
Where does my money go?
Straight to the seller. Skill Harbor never processes payments: checkout happens on the seller’s own page, usually Stripe.
What does the ✓ next to a creator’s name mean?
It means we confirmed the identity of the person behind the listing. It says nothing about the code itself — always check a skill before installing it.