convex-component-authoring
installsforks
How to install convex-component-authoring?
waynesutton/convexskills/convex-component-authoring
$npx -y skills add waynesutton/convexskills --skill convex-component-authoringHow to create, structure, and publish self-contained Convex components with proper isolation, exports, and dependency management
SKILL.md
| 1 | # Convex Component Authoring |
| 2 | |
| 3 | Create self-contained, reusable Convex components with proper isolation, exports, and dependency management for sharing across projects. |
| 4 | |
| 5 | ## Documentation Sources |
| 6 | |
| 7 | Before implementing, do not assume; fetch the latest documentation: |
| 8 | |
| 9 | - Primary: https://docs.convex.dev/components |
| 10 | - Component Authoring: https://docs.convex.dev/components/authoring |
| 11 | - For broader context: https://docs.convex.dev/llms.txt |
| 12 | |
| 13 | ## Instructions |
| 14 | |
| 15 | ### What Are Convex Components? |
| 16 | |
| 17 | Convex components are self-contained packages that include: |
| 18 | - Database tables (isolated from the main app) |
| 19 | - Functions (queries, mutations, actions) |
| 20 | - TypeScript types and validators |
| 21 | - Optional frontend hooks |
| 22 | |
| 23 | ### Component Structure |
| 24 | |
| 25 | ``` |
| 26 | my-convex-component/ |
| 27 | ├── package.json |
| 28 | ├── tsconfig.json |
| 29 | ├── README.md |
| 30 | ├── src/ |
| 31 | │ ├── index.ts # Main exports |
| 32 | │ ├── component.ts # Component definition |
| 33 | │ ├── schema.ts # Component schema |
| 34 | │ └── functions/ |
| 35 | │ ├── queries.ts |
| 36 | │ ├── mutations.ts |
| 37 | │ └── actions.ts |
| 38 | └── convex.config.ts # Component configuration |
| 39 | ``` |
| 40 | |
| 41 | ### Creating a Component |
| 42 | |
| 43 | #### 1. Component Configuration |
| 44 | |
| 45 | ```typescript |
| 46 | // convex.config.ts |
| 47 | import { defineComponent } from "convex/server"; |
| 48 | |
| 49 | export default defineComponent("myComponent"); |
| 50 | ``` |
| 51 | |
| 52 | #### 2. Component Schema |
| 53 | |
| 54 | ```typescript |
| 55 | // src/schema.ts |
| 56 | import { defineSchema, defineTable } from "convex/server"; |
| 57 | import { v } from "convex/values"; |
| 58 | |
| 59 | export default defineSchema({ |
| 60 | // Tables are isolated to this component |
| 61 | items: defineTable({ |
| 62 | name: v.string(), |
| 63 | data: v.any(), |
| 64 | createdAt: v.number(), |
| 65 | }).index("by_name", ["name"]), |
| 66 | |
| 67 | config: defineTable({ |
| 68 | key: v.string(), |
| 69 | value: v.any(), |
| 70 | }).index("by_key", ["key"]), |
| 71 | }); |
| 72 | ``` |
| 73 | |
| 74 | #### 3. Component Definition |
| 75 | |
| 76 | ```typescript |
| 77 | // src/component.ts |
| 78 | import { defineComponent, ComponentDefinition } from "convex/server"; |
| 79 | import schema from "./schema"; |
| 80 | import * as queries from "./functions/queries"; |
| 81 | import * as mutations from "./functions/mutations"; |
| 82 | |
| 83 | const component = defineComponent("myComponent", { |
| 84 | schema, |
| 85 | functions: { |
| 86 | ...queries, |
| 87 | ...mutations, |
| 88 | }, |
| 89 | }); |
| 90 | |
| 91 | export default component; |
| 92 | ``` |
| 93 | |
| 94 | #### 4. Component Functions |
| 95 | |
| 96 | ```typescript |
| 97 | // src/functions/queries.ts |
| 98 | import { query } from "../_generated/server"; |
| 99 | import { v } from "convex/values"; |
| 100 | |
| 101 | export const list = query({ |
| 102 | args: { |
| 103 | limit: v.optional(v.number()), |
| 104 | }, |
| 105 | returns: v.array(v.object({ |
| 106 | _id: v.id("items"), |
| 107 | name: v.string(), |
| 108 | data: v.any(), |
| 109 | createdAt: v.number(), |
| 110 | })), |
| 111 | handler: async (ctx, args) => { |
| 112 | return await ctx.db |
| 113 | .query("items") |
| 114 | .order("desc") |
| 115 | .take(args.limit ?? 10); |
| 116 | }, |
| 117 | }); |
| 118 | |
| 119 | export const get = query({ |
| 120 | args: { name: v.string() }, |
| 121 | returns: v.union(v.object({ |
| 122 | _id: v.id("items"), |
| 123 | name: v.string(), |
| 124 | data: v.any(), |
| 125 | }), v.null()), |
| 126 | handler: async (ctx, args) => { |
| 127 | return await ctx.db |
| 128 | .query("items") |
| 129 | .withIndex("by_name", (q) => q.eq("name", args.name)) |
| 130 | .unique(); |
| 131 | }, |
| 132 | }); |
| 133 | ``` |
| 134 | |
| 135 | ```typescript |
| 136 | // src/functions/mutations.ts |
| 137 | import { mutation } from "../_generated/server"; |
| 138 | import { v } from "convex/values"; |
| 139 | |
| 140 | export const create = mutation({ |
| 141 | args: { |
| 142 | name: v.string(), |
| 143 | data: v.any(), |
| 144 | }, |
| 145 | returns: v.id("items"), |
| 146 | handler: async (ctx, args) => { |
| 147 | return await ctx.db.insert("items", { |
| 148 | name: args.name, |
| 149 | data: args.data, |
| 150 | createdAt: Date.now(), |
| 151 | }); |
| 152 | }, |
| 153 | }); |
| 154 | |
| 155 | export const update = mutation({ |
| 156 | args: { |
| 157 | id: v.id("items"), |
| 158 | data: v.any(), |
| 159 | }, |
| 160 | returns: v.null(), |
| 161 | handler: async (ctx, args) => { |
| 162 | await ctx.db.patch(args.id, { data: args.data }); |
| 163 | return null; |
| 164 | }, |
| 165 | }); |
| 166 | |
| 167 | export const remove = mutation({ |
| 168 | args: { id: v.id("items") }, |
| 169 | returns: v.null(), |
| 170 | handler: async (ctx, args) => { |
| 171 | await ctx.db.delete(args.id); |
| 172 | return null; |
| 173 | }, |
| 174 | }); |
| 175 | ``` |
| 176 | |
| 177 | #### 5. Main Exports |
| 178 | |
| 179 | ```typescript |
| 180 | // src/index.ts |
| 181 | export { default as component } from "./component"; |
| 182 | export * from "./functions/queries"; |
| 183 | export * from "./functions/mutations"; |
| 184 | |
| 185 | // Export types for consumers |
| 186 | export type { Id } from "./_generated/dataModel"; |
| 187 | ``` |
| 188 | |
| 189 | ### Using a Component |
| 190 | |
| 191 | ```typescript |
| 192 | // In the consuming app's convex/convex.config.ts |
| 193 | import { defineApp } from "convex/server"; |
| 194 | import myComponent from "my-convex-component"; |
| 195 | |
| 196 | const app = defineApp(); |
| 197 | |
| 198 | app.use(myComponent, { name: "myComponent" }); |
| 199 | |
| 200 | export default app; |
| 201 | ``` |
| 202 | |
| 203 | ```typescript |
| 204 | // In the consuming app's code |
| 205 | import { useQuery, useMutation } from "convex/react"; |
| 206 | import { api } from "../convex/_generated/api"; |
| 207 | |
| 208 | function MyApp() { |
| 209 | // Access component functions through the app's API |
| 210 | const items = useQuery(api.myComponent.list, { limit: 10 }); |
| 211 | const createItem = useMutation(api.myCompon |
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
