convex-functions
installsforks
How to install convex-functions?
waynesutton/convexskills/convex-functions
$npx -y skills add waynesutton/convexskills --skill convex-functionsWriting queries, mutations, actions, and HTTP actions with proper argument validation, error handling, internal functions, and runtime considerations
SKILL.md
| 1 | # Convex Functions |
| 2 | |
| 3 | Master Convex functions including queries, mutations, actions, and HTTP endpoints with proper validation, error handling, and runtime considerations. |
| 4 | |
| 5 | ## Code Quality |
| 6 | |
| 7 | All examples in this skill comply with @convex-dev/eslint-plugin rules: |
| 8 | |
| 9 | - Object syntax with `handler` property |
| 10 | - Argument validators on all functions |
| 11 | - Explicit table names in database operations |
| 12 | |
| 13 | See the Code Quality section in [convex-best-practices](../convex-best-practices/SKILL.md) for linting setup. |
| 14 | |
| 15 | ## Documentation Sources |
| 16 | |
| 17 | Before implementing, do not assume; fetch the latest documentation: |
| 18 | |
| 19 | - Primary: https://docs.convex.dev/functions |
| 20 | - Query Functions: https://docs.convex.dev/functions/query-functions |
| 21 | - Mutation Functions: https://docs.convex.dev/functions/mutation-functions |
| 22 | - Actions: https://docs.convex.dev/functions/actions |
| 23 | - HTTP Actions: https://docs.convex.dev/functions/http-actions |
| 24 | - For broader context: https://docs.convex.dev/llms.txt |
| 25 | |
| 26 | ## Instructions |
| 27 | |
| 28 | ### Function Types Overview |
| 29 | |
| 30 | | Type | Database Access | External APIs | Caching | Use Case | |
| 31 | | ----------- | ------------------------ | ------------- | ------------- | --------------------- | |
| 32 | | Query | Read-only | No | Yes, reactive | Fetching data | |
| 33 | | Mutation | Read/Write | No | No | Modifying data | |
| 34 | | Action | Via runQuery/runMutation | Yes | No | External integrations | |
| 35 | | HTTP Action | Via runQuery/runMutation | Yes | No | Webhooks, APIs | |
| 36 | |
| 37 | ### Queries |
| 38 | |
| 39 | Queries are reactive, cached, and read-only: |
| 40 | |
| 41 | ```typescript |
| 42 | import { query } from "./_generated/server"; |
| 43 | import { v } from "convex/values"; |
| 44 | |
| 45 | export const getUser = query({ |
| 46 | args: { userId: v.id("users") }, |
| 47 | returns: v.union( |
| 48 | v.object({ |
| 49 | _id: v.id("users"), |
| 50 | _creationTime: v.number(), |
| 51 | name: v.string(), |
| 52 | email: v.string(), |
| 53 | }), |
| 54 | v.null(), |
| 55 | ), |
| 56 | handler: async (ctx, args) => { |
| 57 | return await ctx.db.get("users", args.userId); |
| 58 | }, |
| 59 | }); |
| 60 | |
| 61 | // Query with index |
| 62 | export const listUserTasks = query({ |
| 63 | args: { userId: v.id("users") }, |
| 64 | returns: v.array( |
| 65 | v.object({ |
| 66 | _id: v.id("tasks"), |
| 67 | _creationTime: v.number(), |
| 68 | title: v.string(), |
| 69 | completed: v.boolean(), |
| 70 | }), |
| 71 | ), |
| 72 | handler: async (ctx, args) => { |
| 73 | return await ctx.db |
| 74 | .query("tasks") |
| 75 | .withIndex("by_user", (q) => q.eq("userId", args.userId)) |
| 76 | .order("desc") |
| 77 | .collect(); |
| 78 | }, |
| 79 | }); |
| 80 | ``` |
| 81 | |
| 82 | ### Mutations |
| 83 | |
| 84 | Mutations modify the database and are transactional: |
| 85 | |
| 86 | ```typescript |
| 87 | import { mutation } from "./_generated/server"; |
| 88 | import { v } from "convex/values"; |
| 89 | import { ConvexError } from "convex/values"; |
| 90 | |
| 91 | export const createTask = mutation({ |
| 92 | args: { |
| 93 | title: v.string(), |
| 94 | userId: v.id("users"), |
| 95 | }, |
| 96 | returns: v.id("tasks"), |
| 97 | handler: async (ctx, args) => { |
| 98 | // Validate user exists |
| 99 | const user = await ctx.db.get("users", args.userId); |
| 100 | if (!user) { |
| 101 | throw new ConvexError("User not found"); |
| 102 | } |
| 103 | |
| 104 | return await ctx.db.insert("tasks", { |
| 105 | title: args.title, |
| 106 | userId: args.userId, |
| 107 | completed: false, |
| 108 | createdAt: Date.now(), |
| 109 | }); |
| 110 | }, |
| 111 | }); |
| 112 | |
| 113 | export const deleteTask = mutation({ |
| 114 | args: { taskId: v.id("tasks") }, |
| 115 | returns: v.null(), |
| 116 | handler: async (ctx, args) => { |
| 117 | await ctx.db.delete("tasks", args.taskId); |
| 118 | return null; |
| 119 | }, |
| 120 | }); |
| 121 | ``` |
| 122 | |
| 123 | ### Actions |
| 124 | |
| 125 | Actions can call external APIs but have no direct database access: |
| 126 | |
| 127 | ```typescript |
| 128 | "use node"; |
| 129 | |
| 130 | import { action } from "./_generated/server"; |
| 131 | import { v } from "convex/values"; |
| 132 | import { api, internal } from "./_generated/api"; |
| 133 | |
| 134 | export const sendEmail = action({ |
| 135 | args: { |
| 136 | to: v.string(), |
| 137 | subject: v.string(), |
| 138 | body: v.string(), |
| 139 | }, |
| 140 | returns: v.object({ success: v.boolean() }), |
| 141 | handler: async (ctx, args) => { |
| 142 | // Call external API |
| 143 | const response = await fetch("https://api.email.com/send", { |
| 144 | method: "POST", |
| 145 | headers: { "Content-Type": "application/json" }, |
| 146 | body: JSON.stringify(args), |
| 147 | }); |
| 148 | |
| 149 | return { success: response.ok }; |
| 150 | }, |
| 151 | }); |
| 152 | |
| 153 | // Action calling queries and mutations |
| 154 | export const processOrder = action({ |
| 155 | args: { orderId: v.id("orders") }, |
| 156 | returns: v.null(), |
| 157 | handler: async (ctx, args) => { |
| 158 | // Read data via query |
| 159 | const order = await ctx.runQuery(api.orders.get, { orderId: args.orderId }); |
| 160 | |
| 161 | if (!order) { |
| 162 | throw new Error("Order not found"); |
| 163 | } |
| 164 | |
| 165 | // Call external payment API |
| 166 | const paymentResult = await processPayment(order); |
| 167 | |
| 168 | // Update database via mutation |
| 169 | await ctx.runMutation(internal.orders.updateStatus, { |
| 170 | orderId: args.orderId, |
People who liked this also viewed
6 picksType
- azure-storageAzure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier,SkillsJul 2026
- supabase-postgres-best-practicesPostgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.SkillsJul 2026
- supabaseUse when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, SkillsJul 2026
- convex-quickstartCreates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.SkillsJul 2026
- convex-performance-auditAudits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.SkillsJul 2026
- convex-setup-authSets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.SkillsJul 2026
