convex-create-component

Name: convex-create-component
Author: get-convex

89kinstalls8forks

How to install convex-create-component?

get-convex/agent-skills/convex-create-component

$npx -y skills add get-convex/agent-skills --skill convex-create-component

Installs into the current project.

Summary

Builds reusable Convex components with isolated tables and app-facing APIs. Use for new components, reusable backend modules, integrations, or component boundary work.

Files · 1

View on GitHub

SKILL.md

1	# Convex Create Component
2
3	Create reusable Convex components with clear boundaries and a small app-facing
4	API.
5
6	## When to Use
7
8	- Creating a new Convex component in an existing app
9	- Extracting reusable backend logic into a component
10	- Building a third-party integration that should own its own tables and
11	workflows
12	- Packaging Convex functionality for reuse across multiple apps
13
14	## When Not to Use
15
16	- One-off business logic that belongs in the main app
17	- Thin utilities that do not need Convex tables or functions
18	- App-level orchestration that should stay in `convex/`
19	- Cases where a normal TypeScript library is enough
20
21	## Workflow
22
23	1. Ask the user what they are building and what the end goal is. If the repo
24	already makes the answer obvious, say so and confirm before proceeding.
25	2. Choose the shape using the decision tree below and read the matching
26	reference file.
27	3. Decide whether a component is justified. Prefer normal app code or a regular
28	library if the feature does not need isolated tables, backend functions, or
29	reusable persistent state.
30	4. Make a short plan for:
31	- what tables the component owns
32	- what public functions it exposes
33	- what data must be passed in from the app (auth, env vars, parent IDs)
34	- what stays in the app as wrappers or HTTP mounts
35	5. Create the component structure with `convex.config.ts`, `schema.ts`, and
36	function files.
37	6. Implement functions using the component's own `./_generated/server` imports,
38	not the app's generated files.
39	7. Wire the component into the app with `app.use(...)`. If the app does not
40	already have `convex/convex.config.ts`, create it.
41	8. Call the component from the app through `components.<name>` using
42	`ctx.runQuery`, `ctx.runMutation`, or `ctx.runAction`.
43	9. If React clients, HTTP callers, or public APIs need access, create wrapper
44	functions in the app instead of exposing component functions directly.
45	10. Run `npx convex dev` and fix codegen, type, or boundary issues before
46	finishing.
47
48	## Choose the Shape
49
50	Ask the user, then pick one path:
51
52	\| Goal \| Shape \| Reference \|
53	\| ------------------------------------------------- \| ---------------- \| ----------------------------------- \|
54	\| Component for this app only \| Local \| `references/local-components.md` \|
55	\| Publish or share across apps \| Packaged \| `references/packaged-components.md` \|
56	\| User explicitly needs local + shared library code \| Hybrid \| `references/hybrid-components.md` \|
57	\| Not sure \| Default to local \| `references/local-components.md` \|
58
59	Read exactly one reference file before proceeding.
60
61	## Default Approach
62
63	Unless the user explicitly wants an npm package, default to a local component:
64
65	- Put it under `convex/components/<componentName>/`
66	- Define it with `defineComponent(...)` in its own `convex.config.ts`
67	- Install it from the app's `convex/convex.config.ts` with `app.use(...)`
68	- Let `npx convex dev` generate the component's own `_generated/` files
69
70	## Component Skeleton
71
72	A minimal local component with a table and two functions, plus the app wiring.
73
74	```ts
75	// convex/components/notifications/convex.config.ts
76	import { defineComponent } from "convex/server";
77
78	export default defineComponent("notifications");
79	```
80
81	```ts
82	// convex/components/notifications/schema.ts
83	import { defineSchema, defineTable } from "convex/server";
84	import { v } from "convex/values";
85
86	export default defineSchema({
87	notifications: defineTable({
88	userId: v.string(),
89	message: v.string(),
90	read: v.boolean(),
91	}).index("by_user_read", ["userId", "read"]),
92	});
93	```
94
95	```ts
96	// convex/components/notifications/lib.ts
97	import { v } from "convex/values";
98	import { mutation, query } from "./_generated/server.js";
99
100	export const send = mutation({
101	args: { userId: v.string(), message: v.string() },
102	returns: v.id("notifications"),
103	handler: async (ctx, args) => {
104	return await ctx.db.insert("notifications", {
105	userId: args.userId,
106	message: args.message,
107	read: false,
108	});
109	},
110	});
111
112	export const listUnread = query({
113	args: { userId: v.string() },
114	returns: v.array(
115	v.object({
116	_id: v.id("notifications"),
117	_creationTime: v.number(),
118	userId: v.string(),
119	message: v.string(),
120	read: v.boolean(),
121	}),
122	),
123	handler: async (ctx, args) => {
124	return await ctx.db
125	.query("notifications")
126	.withIndex("by_user_read", (q) =>
127	q.eq("userId", args.userId).eq("read", false),
128	)
129	.collect();
130	},
131	});
132	```
133
134	```ts
135	// convex/convex.config.ts
136	import { defineApp } from "convex/server";
137	import notifications fro

People who liked this also viewed

6 picks

Type

convex-create-component

89kinstalls8forks

View on GitHub

How to install convex-create-component?

get-convex/agent-skills/convex-create-component

$npx -y skills add get-convex/agent-skills --skill convex-create-component

Installs into the current project.

Summary

Builds reusable Convex components with isolated tables and app-facing APIs. Use for new components, reusable backend modules, integrations, or component boundary work.

Files · 1

View on GitHub

SKILL.md

1	# Convex Create Component
2
3	Create reusable Convex components with clear boundaries and a small app-facing
4	API.
5
6	## When to Use
7
8	- Creating a new Convex component in an existing app
9	- Extracting reusable backend logic into a component
10	- Building a third-party integration that should own its own tables and
11	workflows
12	- Packaging Convex functionality for reuse across multiple apps
13
14	## When Not to Use
15
16	- One-off business logic that belongs in the main app
17	- Thin utilities that do not need Convex tables or functions
18	- App-level orchestration that should stay in `convex/`
19	- Cases where a normal TypeScript library is enough
20
21	## Workflow
22
23	1. Ask the user what they are building and what the end goal is. If the repo
24	already makes the answer obvious, say so and confirm before proceeding.
25	2. Choose the shape using the decision tree below and read the matching
26	reference file.
27	3. Decide whether a component is justified. Prefer normal app code or a regular
28	library if the feature does not need isolated tables, backend functions, or
29	reusable persistent state.
30	4. Make a short plan for:
31	- what tables the component owns
32	- what public functions it exposes
33	- what data must be passed in from the app (auth, env vars, parent IDs)
34	- what stays in the app as wrappers or HTTP mounts
35	5. Create the component structure with `convex.config.ts`, `schema.ts`, and
36	function files.
37	6. Implement functions using the component's own `./_generated/server` imports,
38	not the app's generated files.
39	7. Wire the component into the app with `app.use(...)`. If the app does not
40	already have `convex/convex.config.ts`, create it.
41	8. Call the component from the app through `components.<name>` using
42	`ctx.runQuery`, `ctx.runMutation`, or `ctx.runAction`.
43	9. If React clients, HTTP callers, or public APIs need access, create wrapper
44	functions in the app instead of exposing component functions directly.
45	10. Run `npx convex dev` and fix codegen, type, or boundary issues before
46	finishing.
47
48	## Choose the Shape
49
50	Ask the user, then pick one path:
51
52	\| Goal \| Shape \| Reference \|
53	\| ------------------------------------------------- \| ---------------- \| ----------------------------------- \|
54	\| Component for this app only \| Local \| `references/local-components.md` \|
55	\| Publish or share across apps \| Packaged \| `references/packaged-components.md` \|
56	\| User explicitly needs local + shared library code \| Hybrid \| `references/hybrid-components.md` \|
57	\| Not sure \| Default to local \| `references/local-components.md` \|
58
59	Read exactly one reference file before proceeding.
60
61	## Default Approach
62
63	Unless the user explicitly wants an npm package, default to a local component:
64
65	- Put it under `convex/components/<componentName>/`
66	- Define it with `defineComponent(...)` in its own `convex.config.ts`
67	- Install it from the app's `convex/convex.config.ts` with `app.use(...)`
68	- Let `npx convex dev` generate the component's own `_generated/` files
69
70	## Component Skeleton
71
72	A minimal local component with a table and two functions, plus the app wiring.
73
74	```ts
75	// convex/components/notifications/convex.config.ts
76	import { defineComponent } from "convex/server";
77
78	export default defineComponent("notifications");
79	```
80
81	```ts
82	// convex/components/notifications/schema.ts
83	import { defineSchema, defineTable } from "convex/server";
84	import { v } from "convex/values";
85
86	export default defineSchema({
87	notifications: defineTable({
88	userId: v.string(),
89	message: v.string(),
90	read: v.boolean(),
91	}).index("by_user_read", ["userId", "read"]),
92	});
93	```
94
95	```ts
96	// convex/components/notifications/lib.ts
97	import { v } from "convex/values";
98	import { mutation, query } from "./_generated/server.js";
99
100	export const send = mutation({
101	args: { userId: v.string(), message: v.string() },
102	returns: v.id("notifications"),
103	handler: async (ctx, args) => {
104	return await ctx.db.insert("notifications", {
105	userId: args.userId,
106	message: args.message,
107	read: false,
108	});
109	},
110	});
111
112	export const listUnread = query({
113	args: { userId: v.string() },
114	returns: v.array(
115	v.object({
116	_id: v.id("notifications"),
117	_creationTime: v.number(),
118	userId: v.string(),
119	message: v.string(),
120	read: v.boolean(),
121	}),
122	),
123	handler: async (ctx, args) => {
124	return await ctx.db
125	.query("notifications")
126	.withIndex("by_user_read", (q) =>
127	q.eq("userId", args.userId).eq("read", false),
128	)
129	.collect();
130	},
131	});
132	```
133
134	```ts
135	// convex/convex.config.ts
136	import { defineApp } from "convex/server";
137	import notifications fro

People who liked this also viewed

6 picks

Type