convex-best-practices

Name: convex-best-practices
Author: waynesutton

127installs31forks

How to install convex-best-practices?

waynesutton/convexskills/convex-best-practices

$npx -y skills add waynesutton/convexskills --skill convex-best-practices

Installs into the current project.

Summary

Guidelines for building production-ready Convex apps covering function organization, query patterns, validation, TypeScript usage, error handling, and the Zen of Convex design philosophy

Files · 1

View on GitHub

SKILL.md

1	# Convex Best Practices
2
3	Build production-ready Convex applications by following established patterns for function organization, query optimization, validation, TypeScript usage, and error handling.
4
5	## Code Quality
6
7	All patterns in this skill comply with `@convex-dev/eslint-plugin`. Install it for build-time validation:
8
9	```bash
10	npm i @convex-dev/eslint-plugin --save-dev
11	```
12
13	```js
14	// eslint.config.js
15	import { defineConfig } from "eslint/config";
16	import convexPlugin from "@convex-dev/eslint-plugin";
17
18	export default defineConfig([
19	...convexPlugin.configs.recommended,
20	]);
21	```
22
23	The plugin enforces four rules:
24
25	\| Rule \| What it enforces \|
26	\| ----------------------------------- \| --------------------------------- \|
27	\| `no-old-registered-function-syntax` \| Object syntax with `handler` \|
28	\| `require-argument-validators` \| `args: {}` on all functions \|
29	\| `explicit-table-ids` \| Table name in db operations \|
30	\| `import-wrong-runtime` \| No Node imports in Convex runtime \|
31
32	Docs: https://docs.convex.dev/eslint
33
34	## Documentation Sources
35
36	Before implementing, do not assume; fetch the latest documentation:
37
38	- Primary: https://docs.convex.dev/understanding/best-practices/
39	- Error Handling: https://docs.convex.dev/functions/error-handling
40	- Write Conflicts: https://docs.convex.dev/error#1
41	- For broader context: https://docs.convex.dev/llms.txt
42
43	## Instructions
44
45	### The Zen of Convex
46
47	1. Convex manages the hard parts - Let Convex handle caching, real-time sync, and consistency
48	2. Functions are the API - Design your functions as your application's interface
49	3. Schema is truth - Define your data model explicitly in schema.ts
50	4. TypeScript everywhere - Leverage end-to-end type safety
51	5. Queries are reactive - Think in terms of subscriptions, not requests
52
53	### Function Organization
54
55	Organize your Convex functions by domain:
56
57	```typescript
58	// convex/users.ts - User-related functions
59	import { query, mutation } from "./_generated/server";
60	import { v } from "convex/values";
61
62	export const get = query({
63	args: { userId: v.id("users") },
64	returns: v.union(
65	v.object({
66	_id: v.id("users"),
67	_creationTime: v.number(),
68	name: v.string(),
69	email: v.string(),
70	}),
71	v.null(),
72	),
73	handler: async (ctx, args) => {
74	return await ctx.db.get("users", args.userId);
75	},
76	});
77	```
78
79	### Argument and Return Validation
80
81	Always define validators for arguments AND return types:
82
83	```typescript
84	export const createTask = mutation({
85	args: {
86	title: v.string(),
87	description: v.optional(v.string()),
88	priority: v.union(v.literal("low"), v.literal("medium"), v.literal("high")),
89	},
90	returns: v.id("tasks"),
91	handler: async (ctx, args) => {
92	return await ctx.db.insert("tasks", {
93	title: args.title,
94	description: args.description,
95	priority: args.priority,
96	completed: false,
97	createdAt: Date.now(),
98	});
99	},
100	});
101	```
102
103	### Query Patterns
104
105	Use indexes instead of filters for efficient queries:
106
107	```typescript
108	// Schema with index
109	export default defineSchema({
110	tasks: defineTable({
111	userId: v.id("users"),
112	status: v.string(),
113	createdAt: v.number(),
114	})
115	.index("by_user", ["userId"])
116	.index("by_user_and_status", ["userId", "status"]),
117	});
118
119	// Query using index
120	export const getTasksByUser = query({
121	args: { userId: v.id("users") },
122	returns: v.array(
123	v.object({
124	_id: v.id("tasks"),
125	_creationTime: v.number(),
126	userId: v.id("users"),
127	status: v.string(),
128	createdAt: v.number(),
129	}),
130	),
131	handler: async (ctx, args) => {
132	return await ctx.db
133	.query("tasks")
134	.withIndex("by_user", (q) => q.eq("userId", args.userId))
135	.order("desc")
136	.collect();
137	},
138	});
139	```
140
141	### Error Handling
142
143	Use ConvexError for user-facing errors:
144
145	```typescript
146	import { ConvexError } from "convex/values";
147
148	export const updateTask = mutation({
149	args: {
150	taskId: v.id("tasks"),
151	title: v.string(),
152	},
153	returns: v.null(),
154	handler: async (ctx, args) => {
155	const task = await ctx.db.get("tasks", args.taskId);
156
157	if (!task) {
158	throw new ConvexError({
159	code: "NOT_FOUND",
160	message: "Task not found",
161	});
162	}
163
164	await ctx.db.patch("tasks", args.taskId, { title: args.title });
165	return null;
166	},
167	});
168	```
169
170	### Avoiding Write Conflicts (Optimistic Concurrency Control)
171
172	Convex uses OCC. Follow these patterns to minimize conflicts:
173
174	```typescript
175	// GOOD: Make mutations idempotent
176	export const completeTask = mutation({
177	args: { taskId: v.id("tasks") },
178	returns: v.null(),
179	handler: async (ctx, args) => {
180	const task = await ctx.db.get("tasks", args.taskId);
181
182	// E

People who liked this also viewed

6 picks

Type

convex-best-practices

127installs31forks

View on GitHub

How to install convex-best-practices?

waynesutton/convexskills/convex-best-practices

$npx -y skills add waynesutton/convexskills --skill convex-best-practices

Installs into the current project.

Summary

Guidelines for building production-ready Convex apps covering function organization, query patterns, validation, TypeScript usage, error handling, and the Zen of Convex design philosophy

Files · 1

View on GitHub

SKILL.md

1	# Convex Best Practices
2
3	Build production-ready Convex applications by following established patterns for function organization, query optimization, validation, TypeScript usage, and error handling.
4
5	## Code Quality
6
7	All patterns in this skill comply with `@convex-dev/eslint-plugin`. Install it for build-time validation:
8
9	```bash
10	npm i @convex-dev/eslint-plugin --save-dev
11	```
12
13	```js
14	// eslint.config.js
15	import { defineConfig } from "eslint/config";
16	import convexPlugin from "@convex-dev/eslint-plugin";
17
18	export default defineConfig([
19	...convexPlugin.configs.recommended,
20	]);
21	```
22
23	The plugin enforces four rules:
24
25	\| Rule \| What it enforces \|
26	\| ----------------------------------- \| --------------------------------- \|
27	\| `no-old-registered-function-syntax` \| Object syntax with `handler` \|
28	\| `require-argument-validators` \| `args: {}` on all functions \|
29	\| `explicit-table-ids` \| Table name in db operations \|
30	\| `import-wrong-runtime` \| No Node imports in Convex runtime \|
31
32	Docs: https://docs.convex.dev/eslint
33
34	## Documentation Sources
35
36	Before implementing, do not assume; fetch the latest documentation:
37
38	- Primary: https://docs.convex.dev/understanding/best-practices/
39	- Error Handling: https://docs.convex.dev/functions/error-handling
40	- Write Conflicts: https://docs.convex.dev/error#1
41	- For broader context: https://docs.convex.dev/llms.txt
42
43	## Instructions
44
45	### The Zen of Convex
46
47	1. Convex manages the hard parts - Let Convex handle caching, real-time sync, and consistency
48	2. Functions are the API - Design your functions as your application's interface
49	3. Schema is truth - Define your data model explicitly in schema.ts
50	4. TypeScript everywhere - Leverage end-to-end type safety
51	5. Queries are reactive - Think in terms of subscriptions, not requests
52
53	### Function Organization
54
55	Organize your Convex functions by domain:
56
57	```typescript
58	// convex/users.ts - User-related functions
59	import { query, mutation } from "./_generated/server";
60	import { v } from "convex/values";
61
62	export const get = query({
63	args: { userId: v.id("users") },
64	returns: v.union(
65	v.object({
66	_id: v.id("users"),
67	_creationTime: v.number(),
68	name: v.string(),
69	email: v.string(),
70	}),
71	v.null(),
72	),
73	handler: async (ctx, args) => {
74	return await ctx.db.get("users", args.userId);
75	},
76	});
77	```
78
79	### Argument and Return Validation
80
81	Always define validators for arguments AND return types:
82
83	```typescript
84	export const createTask = mutation({
85	args: {
86	title: v.string(),
87	description: v.optional(v.string()),
88	priority: v.union(v.literal("low"), v.literal("medium"), v.literal("high")),
89	},
90	returns: v.id("tasks"),
91	handler: async (ctx, args) => {
92	return await ctx.db.insert("tasks", {
93	title: args.title,
94	description: args.description,
95	priority: args.priority,
96	completed: false,
97	createdAt: Date.now(),
98	});
99	},
100	});
101	```
102
103	### Query Patterns
104
105	Use indexes instead of filters for efficient queries:
106
107	```typescript
108	// Schema with index
109	export default defineSchema({
110	tasks: defineTable({
111	userId: v.id("users"),
112	status: v.string(),
113	createdAt: v.number(),
114	})
115	.index("by_user", ["userId"])
116	.index("by_user_and_status", ["userId", "status"]),
117	});
118
119	// Query using index
120	export const getTasksByUser = query({
121	args: { userId: v.id("users") },
122	returns: v.array(
123	v.object({
124	_id: v.id("tasks"),
125	_creationTime: v.number(),
126	userId: v.id("users"),
127	status: v.string(),
128	createdAt: v.number(),
129	}),
130	),
131	handler: async (ctx, args) => {
132	return await ctx.db
133	.query("tasks")
134	.withIndex("by_user", (q) => q.eq("userId", args.userId))
135	.order("desc")
136	.collect();
137	},
138	});
139	```
140
141	### Error Handling
142
143	Use ConvexError for user-facing errors:
144
145	```typescript
146	import { ConvexError } from "convex/values";
147
148	export const updateTask = mutation({
149	args: {
150	taskId: v.id("tasks"),
151	title: v.string(),
152	},
153	returns: v.null(),
154	handler: async (ctx, args) => {
155	const task = await ctx.db.get("tasks", args.taskId);
156
157	if (!task) {
158	throw new ConvexError({
159	code: "NOT_FOUND",
160	message: "Task not found",
161	});
162	}
163
164	await ctx.db.patch("tasks", args.taskId, { title: args.title });
165	return null;
166	},
167	});
168	```
169
170	### Avoiding Write Conflicts (Optimistic Concurrency Control)
171
172	Convex uses OCC. Follow these patterns to minimize conflicts:
173
174	```typescript
175	// GOOD: Make mutations idempotent
176	export const completeTask = mutation({
177	args: { taskId: v.id("tasks") },
178	returns: v.null(),
179	handler: async (ctx, args) => {
180	const task = await ctx.db.get("tasks", args.taskId);
181
182	// E

People who liked this also viewed

6 picks

Type