convex-component-authoring

Convex component authoring

Produces a self contained component: its own convex.config.ts, schema, functions, and a typed client wrapper the parent app calls. The one rule: a component cannot read the parent's tables, ctx.auth, or process.env. Whatever it needs, the app passes in as arguments.

When to reach for this

• Extracting a feature (counters, rate limits, audit logs, notifications) into a package
• Building something for the Convex component directory
• A component's functions are missing from components.<name> in the parent app
• A third party integration should own its own tables and background jobs
• The same backend module is needed in several apps

Component or helper function

Need	Use
Shared logic over the app's own tables	Plain TypeScript helper in convex/lib/
Its own tables with a schema the app cannot touch	Component
Isolated functions that run in their own transaction	Component
Reuse across apps with one install line	Component
A React hook or client utility only	npm library, no component

If the feature does not need persistent state behind an API boundary, a helper function is less work and easier to type.

Folder layout

my-component/
  package.json
  src/
    component/
      convex.config.ts     # defineComponent("counter")
      schema.ts            # tables only this component can see
      public.ts            # queries, mutations, actions
      _generated/          # created by npx convex codegen
    client/
      index.ts             # wrapper class the app imports
  example/
    convex/
      convex.config.ts     # app.use(counter) for local testing

For a local only component, put the component/ contents at convex/components/<name>/ and skip client/ and package.json.

Define the component

// src/component/convex.config.ts
import { defineComponent } from "convex/server";

const component = defineComponent("counter");
export default component;

// src/component/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  counters: defineTable({
    name: v.string(),
    value: v.number(),
  }).index("by_name", ["name"]),
});

Functions import query and mutation from the component's own _generated/server, never from the app's. Every public function needs args and returns validators; without them the parent sees any.